biopipen 0.21.0__py3-none-any.whl → 0.34.26__py3-none-any.whl

biopipen/ns/tcr.py

@@ -1,10 +1,11 @@
 """Tools to analyze single-cell TCR sequencing data"""
-
+from pipen.utils import mark
 from ..core.defaults import SCRIPT_DIR
 from ..core.proc import Proc
 from ..core.config import config
 
 
+@mark(deprecated="{proc.name} is deprecated, use ScRepLoading instead.")
 class ImmunarchLoading(Proc):
     """Immuarch - Loading data
 
@@ -39,12 +40,15 @@ class ImmunarchLoading(Proc):
             information.
 
     Output:
-        rdsfile: The RDS file with the data and metadata
-        metatxt: The meta data of the cells, used to attach to the Seurat object
+        rdsfile: The RDS file with the data and metadata, which can be processed by
+            other `immunarch` functions.
+        metatxt: The meta data at cell level, which can be used to attach to the Seurat object
 
     Envs:
         prefix: The prefix to the barcodes. You can use placeholder like `{Sample}_`
-            to use the meta data from the `immunarch` object.
+            to use the meta data from the `immunarch` object. The prefixed barcodes will
+            be saved in `out.metatxt`. The `immunarch` object keeps the original barcodes, but
+            the prefix is saved at `immdata$prefix`.
 
             /// Note
             This option is useful because the barcodes for the cells from scRNA-seq
@@ -61,14 +65,20 @@ class ImmunarchLoading(Proc):
             are not in the same directory, we can link them to a temporary directory
             and pass the temporary directory to `Immunarch`.
             This option is useful when the data files are in different directories.
-        mode (hidden): Either "single" for single chain data or "paired" for
+        mode: Either "single" for single chain data or "paired" for
             paired chain data. For `single`, only TRB chain will be kept
             at `immdata$data`, information for other chains will be
             saved at `immdata$tra` and `immdata$multi`.
-        metacols (list): The columns to be exported to the text file.
+        extracols (list): The extra columns to be exported to the text file.
             You can refer to the
             [immunarch documentation](https://immunarch.com/articles/v2_data.html#immunarch-data-format)
-            for the full list of the columns.
+            to get a sense for the full list of the columns.
+            The columns may vary depending on the data source.
+            The columns from `immdata$meta` and some core columns, including
+            `Barcode`, `CDR3.aa`, `Clones`, `Proportion`, `V.name`, `J.name`, and
+            `D.name` will be exported by default. You can use this option to
+            specify the extra columns to be exported.
+
     """  # noqa: E501
     input = "metafile:file"
     output = [
@@ -79,12 +89,13 @@ class ImmunarchLoading(Proc):
     envs = {
         "tmpdir": config.path.tmpdir,
         "prefix": "{Sample}_",
-        "mode": "single",
-        "metacols": ["Clones", "Proportion", "CDR3.aa"],
+        "mode": "paired",
+        "extracols": [],
     }
     script = "file://../scripts/tcr/ImmunarchLoading.R"
 
 
+@mark(deprecated=True)
 class ImmunarchFilter(Proc):
     """Immunarch - Filter data
 
@@ -163,12 +174,13 @@ class ImmunarchFilter(Proc):
     script = "file://../scripts/tcr/ImmunarchFilter.R"
 
 
+@mark(deprecated="{proc.name} is deprecated, use ClonalStats instead.")
 class Immunarch(Proc):
     """Exploration of Single-cell and Bulk T-cell/Antibody Immune Repertoires
 
     See <https://immunarch.com/articles/web_only/v3_basic_analysis.html>
 
-    After [`ImmunarchLoading`](./ImmunarchLoading.md) loads the raw data into an [immunarch](https://immunarch.com) object,
+    After [`ImmunarchLoading`](!!#biopipennstcrimmunarchloading) loads the raw data into an [immunarch](https://immunarch.com) object,
     this process wraps the functions from [`immunarch`](https://immunarch.com) to do the following:
 
     - Basic statistics, provided by [`immunarch::repExplore`](https://immunarch.com/reference/repExplore.html), such as number of clones or distributions of lengths and counts.
@@ -180,6 +192,7 @@ class Immunarch(Proc):
     - The dynamics of repertoires across time points/samples, provided by [`immunarch::trackClonotypes`](https://immunarch.com/reference/trackClonotypes.html)
     - The spectratype of clonotypes, provided by [`immunarch::spectratype`](https://immunarch.com/reference/spectratype.html)
     - The distributions of kmers and sequence profiles, provided by [`immunarch::getKmers`](https://immunarch.com/reference/getKmers.html)
+    - The V-J junction circos plots, implemented within the script of this process.
 
     Environment Variable Design:
         With different sets of arguments, a single function of the above can perform different tasks.
@@ -218,7 +231,7 @@ class Immunarch(Proc):
         vis_args = { "-plot": "heatmap2" }
         ```
 
-        `-plot` will be translated to `.plot` and then passed to `vis`. See also [Namespace and Environment Variables](../configurations.md#namespace-environment-variables).
+        `-plot` will be translated to `.plot` and then passed to `vis`.
 
         If multiple cases share the same arguments, we can use the following configuration:
 
@@ -321,6 +334,7 @@ class Immunarch(Proc):
         prefix: The prefix to the barcodes. You can use placeholder like `{Sample}_`
             The prefixed barcodes will be used to match the barcodes in `in.metafile`.
             Not used if `in.metafile` is not specified.
+            If `None` (default), `immdata$prefix` will be used.
         volumes (ns): Explore clonotype volume (sizes).
             - by: Groupings when visualize clonotype volumes, passed to the `.by` argument of `vis(imm_vol, .by = <values>)`.
                 Multiple columns should be separated by `,`.
@@ -553,12 +567,13 @@ class Immunarch(Proc):
                     A Gini coefficient of one (or 100 percents) expresses maximal inequality among values (for example where only one person has all the income).
                 - d50: The D50 index.
                     It is the number of types that are needed to cover 50%% of the total abundance.
-                - dxx: The Dxx index.
-                    It is the number of types that are needed to cover xx%% of the total abundance.
-                    The percentage should be specified in the `args` argument using `perc` key.
                 - raref: Species richness from the results of sampling through extrapolation.
             - by: The variables (column names) to group samples.
                 Multiple columns should be separated by `,`.
+            - plot_type (choice): The type of the plot, works when `by` is specified.
+                Not working for `raref`.
+                - box: Boxplot
+                - bar: Barplot with error bars
             - subset: Subset the data before calculating the clonotype volumes.
                 The whole data will be expanded to cell level, and then subsetted.
                 Clone sizes will be re-calculated based on the subsetted data.
@@ -586,6 +601,13 @@ class Immunarch(Proc):
                     - fdr: Benjamini & Hochberg (non-negative)
                     - none: no correction.
             - separate_by: A column name used to separate the samples into different plots.
+            - split_by: A column name used to split the samples into different subplots.
+                Like `separate_by`, but the plots will be put in the same figure.
+                y-axis will be shared, even if `align_y` is `False` or `ymin`/`ymax` are not specified.
+                `ncol` will be ignored.
+            - split_order: The order of the values in `split_by` on the x-axis of the plots.
+                It can also be used for `separate_by` to control the order of the plots.
+                Values can be separated by `,`.
             - align_x (flag): Align the x-axis of multiple plots. Only works for `raref`.
             - align_y (flag): Align the y-axis of multiple plots.
             - ymin (type=float): The minimum value of the y-axis.
@@ -657,13 +679,31 @@ class Immunarch(Proc):
                 The values will be passed to the corresponding arguments above.
                 If any of these arguments are not specified, the default case will be added, with the name `DEFAULT` and the
                 values of `envs.kmers.k`, `envs.kmers.head`, `envs.kmers.vis_args` and `envs.kmers.devpars`.
+        vj_junc (ns): Arguments for VJ junction circos plots.
+            This analysis is not included in `immunarch`. It is a separate implementation using [`circlize`](https://github.com/jokergoo/circlize).
+            - by: Groupings to show VJ usages. Typically, this is the `Sample` column, so that the VJ usages are shown for each sample.
+                But you can also use other columns, such as `Subject` to show the VJ usages for each subject.
+                Multiple columns should be separated by `,`.
+            - by_clones (flag): If True, the VJ usages will be calculated based on the distinct clonotypes, instead of the individual cells.
+            - subset: Subset the data before plotting VJ usages.
+                The whole data will be expanded to cell level, and then subsetted.
+                Clone sizes will be re-calculated based on the subsetted data, which will affect the VJ usages at cell level (by_clones=False).
+            - devpars (ns): The parameters for the plotting device.
+                - width (type=int): The width of the plot.
+                - height (type=int): The height of the plot.
+                - res (type=int): The resolution of the plot.
+            - cases (type=json;order=9): If you have multiple cases, you can use this argument to specify them.
+                The keys will be used as the names of the cases. The values will be passed to the corresponding arguments above.
+                If any of these arguments are not specified, the values in `envs.vj_junc` will be used.
+                If NO cases are specified, the default case will be added, with the name `DEFAULT` and the
+                values of `envs.vj_junc.by`, `envs.vj_junc.by_clones` `envs.vj_junc.subset` and `envs.vj_junc.devpars`.
     """  # noqa: E501
     input = "immdata:file,metafile:file"
     output = "outdir:dir:{{in.immdata | stem}}.immunarch"
     lang = config.lang.rscript
     envs = {
         "mutaters": {},
-        "prefix": "{Sample}_",
+        "prefix": None,
         # basic statistics
         "volumes": {
             "by": None,
@@ -754,9 +794,9 @@ class Immunarch(Proc):
         },
         # Diversity
         "divs": {
-            "filter": None,
             "method": "gini",
             "by": None,
+            "plot_type": "bar",
             "args": {},
             "order": [],
             "test": {
@@ -764,12 +804,14 @@ class Immunarch(Proc):
                 "padjust": "none",
             },
             "separate_by": None,
+            "split_by": None,
+            "split_order": None,
             "align_x": False,
             "align_y": False,
             "log": False,
             "devpars": {
-                "width": 1000,
-                "height": 1000,
+                "width": 800,
+                "height": 800,
                 "res": 100,
             },
             "subset": None,
@@ -801,14 +843,24 @@ class Immunarch(Proc):
             },
             "cases": {},
         },
+        # VJ junction
+        "vj_junc": {
+            "by": "Sample",
+            "by_clones": True,
+            "devpars": {"width": 800, "height": 800, "res": 100},
+            "subset": None,
+            "cases": {},
+        },
     }
     script = "file://../scripts/tcr/Immunarch.R"
     plugin_opts = {
         "report": "file://../reports/tcr/Immunarch.svelte",
         "report_paging": 3,
+        "poplog_max": 999,
     }
 
 
+@mark(deprecated="{proc.name} is deprecated, use ClonalStats instead.")
 class SampleDiversity(Proc):
     """Sample diversity and rarefaction analysis
 
@@ -857,6 +909,7 @@ class SampleDiversity(Proc):
     }
 
 
+@mark(deprecated="{proc.name} is deprecated, use ClonalStats instead.")
 class CloneResidency(Proc):
     """Identification of clone residency
 
@@ -876,7 +929,7 @@ class CloneResidency(Proc):
 
     - Residency plots showing the residency of clones in the two groups
 
-        ![CloneResidency_residency](https://pwwang.github.io/immunopipe/processes/images/CloneResidency.png)
+        ![CloneResidency_residency](https://pwwang.github.io/immunopipe/latest/processes/images/CloneResidency.png)
 
         The points in the plot are jittered to avoid overplotting. The x-axis is the residency in the first group and
         the y-axis is the residency in the second group. The size of the points are relative to the normalized size of
@@ -896,7 +949,7 @@ class CloneResidency(Proc):
 
     - Venn diagrams showing the overlap of the clones in the two groups
 
-        ![CloneResidency_venn](https://pwwang.github.io/immunopipe/processes/images/CloneResidency_venn.png){: width="60%"}
+        ![CloneResidency_venn](https://pwwang.github.io/immunopipe/latest/processes/images/CloneResidency_venn.png){: width="60%"}
 
     Input:
         immdata: The data loaded by `immunarch::repLoad()`
@@ -936,6 +989,12 @@ class CloneResidency(Proc):
             before calculating the clone residency. For example, `Clones > 1` to filter
             out singletons.
         prefix: The prefix of the cell barcodes in the `Seurat` object.
+        upset_ymax: The maximum value of the y-axis in the upset bar plots.
+        upset_trans: The transformation to apply to the y axis of upset bar plots.
+            For example, `log10` or `sqrt`. If not specified, the y axis will be
+            plotted as is. Note that the position of the bar plots will be dodged
+            instead of stacked when the transformation is applied.
+            See also <https://github.com/tidyverse/ggplot2/issues/3671>
         cases (type=json): If you have multiple cases, you can use this argument
             to specify them. The keys will be used as the names of the cases.
             The values will be passed to the corresponding arguments.
@@ -955,6 +1014,8 @@ class CloneResidency(Proc):
         "mutaters": {},
         "subset": None,
         "prefix": "{Sample}_",
+        "upset_ymax": None,
+        "upset_trans": None,
         "cases": {},
     }
     script = "file://../scripts/tcr/CloneResidency.R"
@@ -962,12 +1023,14 @@ class CloneResidency(Proc):
     plugin_opts = {"report": "file://../reports/tcr/CloneResidency.svelte"}
 
 
+@mark(deprecated=True)
 class Immunarch2VDJtools(Proc):
     """Convert immuarch format into VDJtools input formats.
 
     This process converts the [`immunarch`](https://immunarch.com/) object to the
     [`VDJtools`](https://vdjtools-doc.readthedocs.io/en/master/) input files,
-    in order to perform the VJ gene usage analysis by [`VJUsage`](./VJUsage.md) process.
+    in order to perform the VJ gene usage analysis by
+    [`VJUsage`](!!#biopipennstcrvjusage) process.
 
     This process will generally generate a tab-delimited file for each sample,
     with the following columns.
@@ -997,6 +1060,7 @@ class Immunarch2VDJtools(Proc):
     script = "file://../scripts/tcr/Immunarch2VDJtools.R"
 
 
+@mark(deprecated=True)
 class ImmunarchSplitIdents(Proc):
     """Split the data into multiple immunarch datasets by Idents from Seurat
 
@@ -1030,6 +1094,7 @@ class ImmunarchSplitIdents(Proc):
     script = "file://../scripts/tcr/ImmunarchSplitIdents.R"
 
 
+@mark(deprecated="{proc.name} is deprecated, use ClonalStats instead.")
 class VJUsage(Proc):
     """Circos-style V-J usage plot displaying the frequency of
     various V-J junctions using vdjtools.
@@ -1072,6 +1137,7 @@ class VJUsage(Proc):
     plugin_opts = {"report": "file://../reports/tcr/VJUsage.svelte"}
 
 
+@mark(deprecated=True)
 class Attach2Seurat(Proc):
     """Attach the clonal information to a Seurat object as metadata
 
@@ -1097,10 +1163,10 @@ class Attach2Seurat(Proc):
     script = "file://../scripts/tcr/Attach2Seurat.R"
 
 
-class TCRClustering(Proc):
-    """Cluster the TCR clones by their CDR3 sequences
+class CDR3Clustering(Proc):
+    """Cluster the TCR/BCR clones by their CDR3 sequences
 
-    This process is used to cluster TCR clones based on their CDR3 sequences.
+    This process is used to cluster TCR/BCR clones based on their CDR3 sequences.
 
     It uses either
 
@@ -1124,10 +1190,9 @@ class TCRClustering(Proc):
     yield similar results.
 
     A text file will be generated with the cluster assignments for each cell, together
-    with the `immunarch` object (in `R`) with the cluster assignments at `TCR_Clsuter`
-    column. This information will then be merged to the `Seurat` object by
-    [TCRClusters2Seurat](./TCRClusters2Seurat.md).
-    Futher downstream analysis can be performed using the cluster assignments.
+    with the `immunarch` object (in `R`) with the cluster assignments at `CDR3_Clsuter`
+    column. This information will then be merged to a `Seurat` object for further
+    downstream analysis.
 
     The cluster assignments are prefixed with `S_` or `M_` to indicate whether a
     cluster has only one unique CDR3 sequence or multiple CDR3 sequences.
@@ -1135,17 +1200,20 @@ class TCRClustering(Proc):
     CDR3 sequence may be shared by multiple cells.
 
     Input:
-        immfile: The immunarch object in RDS
+        screpfile: The TCR/BCR data object loaded by `scRepertoire::CombineTCR()`,
+            `scRepertoire::CombineBCR()` or `scRepertoire::CombineExpression()`
 
     Output:
-        immfile: The immnuarch object in RDS with TCR cluster information
-        clusterfile: The cluster file.
-            Columns are CDR3.aa, TCR_Cluster, TCR_Cluster_Size and
-            TCR_Cluster_Size1.
-            TCR_Cluster_Size is the number of cells in the cluster.
-            TCR_Cluster_Size1 is the unique CDR3 sequences in the cluster.
+        outfile: The `scRepertoire` object in qs with TCR/BCR cluster information.
+            Column `CDR3_Cluster` will be added to the metadata.
 
     Envs:
+        type (choice): The type of the data.
+            - TCR: T cell receptor data
+            - BCR: B cell receptor data
+            - auto: Automatically detect the type from the data.
+                Try to find TRB or IGH genes in the CTgene column to determine
+                whether it is TCR or BCR data.
         tool (choice): The tool used to do the clustering, either
             [GIANA](https://github.com/s175573/GIANA) or
             [ClusTCR](https://github.com/svalkiers/clusTCR).
@@ -1154,34 +1222,51 @@ class TCRClustering(Proc):
             - ClusTCR: by Sebastiaan Valkiers, etc
         python: The path of python with `GIANA`'s dependencies installed
             or with `clusTCR` installed. Depending on the `tool` you choose.
+        within_sample (flag): Whether to cluster the TCR/BCR clones within each sample.
+            When `in.screpfile` is a `Seurat` object, the samples are marked by
+            the `Sample` column in the metadata.
         args (type=json): The arguments for the clustering tool
             For GIANA, they will be passed to `python GIAna.py`
             See <https://github.com/s175573/GIANA#usage>.
             For ClusTCR, they will be passed to `clustcr.Clustering(...)`
             See <https://svalkiers.github.io/clusTCR/docs/clustering/how-to-use.html#clustering>.
-        on_multi (flag;hidden): Whether to run clustering on
-            multi-chain seq or the seq read and processed by immunarch
+        chain (choice): The TCR/BCR chain to use for clustering.
+            - heavy: The heavy chain, TRB for TCR, IGH for BCR.
+                For TCR, TRB is the second sequence in `CTaa`, separated by `_` if
+                input is a Seurat object; otherwise, it is extracted from the `cdr3_aa2` column.
+                For BCR, IGH is the first sequence in `CTaa`, separated by `_` if
+                input is a Seurat object; otherwise, it is extracted from the `cdr3_aa1` column.
+            - light: The light chain, TRA for TCR, IGL/IGK for BCR.
+                For TCR, TRA is the first sequence in `CTaa`, separated by `_` if
+                input is a Seurat object; otherwise, it is extracted from the `cdr3_aa1` column.
+                For BCR, IGL/IGK is the second sequence in `CTaa`, separated by `_` if
+                input is a Seurat object; otherwise, it is extracted from the `cdr3_aa2` column.
+            - TRA: Only the TRA chain for TCR (light chain).
+            - TRB: Only the TRB chain for TCR (heavy chain).
+            - IGH: Only the IGH chain for BCR (heavy chain).
+            - IGLK: Only the IGL/IGK chain for BCR (light chain).
+            - both: Both sequences from the heavy and light chains (CTaa column).
 
     Requires:
         clusTCR:
             - if: {{ proc.envs.tool == 'ClusTCR' }}
             - check: {{ proc.envs.python }} -c "import clustcr"
     """  # noqa: E501
-    input = "immfile:file"
-    output = [
-        "immfile:file:{{in.immfile | basename}}",
-        "clusterfile:file:{{in.immfile | stem}}.clusters.txt",
-    ]
+    input = "screpfile:file"
+    output = "outfile:file:{{in.screpfile | stem}}.tcr_clustered.qs"
     lang = config.lang.rscript
     envs = {
+        "type": "auto",  # or TCR, BCR
         "tool": "GIANA",  # or ClusTCR
-        "on_multi": False,
         "python": config.lang.python,
+        "within_sample": True,  # whether to cluster the TCR clones within each sample
         "args": {},
+        "chain": "both",
     }
-    script = "file://../scripts/tcr/TCRClustering.R"
+    script = "file://../scripts/tcr/CDR3Clustering.R"
 
 
+@mark(deprecated="{proc.name} is deprecated, use ClonalStats instead.")
 class TCRClusterStats(Proc):
     """Statistics of TCR clusters, generated by `TCRClustering`.
 
@@ -1199,7 +1284,7 @@ class TCRClusterStats(Proc):
         by = "Sample"
         ```
 
-        ![Cluster_size](https://pwwang.github.io/immunopipe/processes/images/TCRClusteringStats_cluster_size.png){: width="80%"}
+        ![Cluster_size](https://pwwang.github.io/immunopipe/latest/processes/images/TCRClusteringStats_cluster_size.png){: width="80%"}
 
         ### Shared clusters
 
@@ -1209,7 +1294,7 @@ class TCRClusterStats(Proc):
         heatmap_meta = ["region"]
         ```
 
-        ![Shared_clusters](https://pwwang.github.io/immunopipe/processes/images/TCRClusteringStats_shared_clusters.png){: width="80%"}
+        ![Shared_clusters](https://pwwang.github.io/immunopipe/latest/processes/images/TCRClusteringStats_shared_clusters.png){: width="80%"}
 
         ### Sample diversity
 
@@ -1218,11 +1303,11 @@ class TCRClusterStats(Proc):
         method = "gini"
         ```
 
-        ![Sample_diversity](https://pwwang.github.io/immunopipe/processes/images/TCRClusteringStats_sample_diversity.png){: width="80%"}
+        ![Sample_diversity](https://pwwang.github.io/immunopipe/latest/processes/images/TCRClusteringStats_sample_diversity.png){: width="80%"}
 
         Compared to the sample diversity using TCR clones:
 
-        ![Sample_diversity](https://pwwang.github.io/immunopipe/processes/images/Immunarch_sample_diversity.png){: width="80%"}
+        ![Sample_diversity](https://pwwang.github.io/immunopipe/latest/processes/images/Immunarch_sample_diversity.png){: width="80%"}
 
     Input:
         immfile: The immunarch object with TCR clusters attached
@@ -1250,6 +1335,10 @@ class TCRClusterStats(Proc):
                 numbers on the heatmap.
             - heatmap_meta (list): The columns of metadata to show on the
                 heatmap.
+            - cluster_rows (flag): Whether to cluster the rows on the heatmap.
+            - sample_order: The order of the samples on the heatmap.
+                Either a string separated by `,` or a list of sample names.
+                This only works for columns if `cluster_rows` is `True`.
             - grouping: The groups to investigate the shared clusters.
                 If specified, venn diagrams will be drawn instead of heatmaps.
                 In such case, `numbers_on_heatmap` and `heatmap_meta` will be
@@ -1313,6 +1402,9 @@ class TCRClusterStats(Proc):
         "shared_clusters": {
             "numbers_on_heatmap": True,
             "heatmap_meta": [],
+            "cluster_rows": True,
+            "sample_order": None,
+            "cluster_rows": True,
             "grouping": None,
             "devpars": {"width": 1000, "height": 1000, "res": 100},
             "cases": {},
@@ -1330,6 +1422,7 @@ class TCRClusterStats(Proc):
     }
 
 
+@mark(deprecated=True)
 class CloneSizeQQPlot(Proc):
     """QQ plot of the clone sizes
 
@@ -1389,15 +1482,9 @@ class CDR3AAPhyschem(Proc):
     - [Zamyatnin, A. A. Protein volume in solution. Prog. Biophys. Mol. Biol. 24, 107-123 (1972).](https://www.sciencedirect.com/science/article/pii/0079610772900053)
 
     Input:
-        immdata: The data loaded by `immunarch::repLoad()`, saved in RDS format
-        srtobj: The `Seurat` object, saved in RDS format, used to get the
-            metadata for each cell (e.g. cell type)
-            It could also be a tab delimited file with `meta.data` of the
-            `Seurat` object.
-            It has to have a `Sample` column, which is used to match the
-            `immdata` object.
-            It is optional, if not provided, the metadata from the `immdata`
-            object will be used.
+        scrfile: The data loaded by `ScRepCombiningExpression`, saved in RDS or qs/qs2 format.
+            The data is actually generated by `scRepertiore::combineExpression()`.
+            The data must have both TRA and TRB chains.
 
     Output:
         outdir: The output directory
@@ -1406,41 +1493,32 @@ class CDR3AAPhyschem(Proc):
         group: The key of group in metadata to define the groups to
             compare. For example, `CellType`, which has cell types annotated
             for each cell in the combined object (immdata + Seurat metadata)
-        comparison (type=json): A dict of two groups, with keys as the
+        comparison (type=auto): A dict of two groups, with keys as the
             group names and values as the group labels. For example,
             ```toml
             Treg = ["CD4 CTL", "CD4 Naive", "CD4 TCM", "CD4 TEM"]
             Tconv = "Tconv"
             ```
-        prefix: The prefix of the cell names (rownames) in the metadata.
-            The prefix is usually not needed in immdata, as the data is stored
-            in the `immdata` object separately for each sample. However, the
-            `Seurat` object has a combined `meta.data` for all the samples,
-            so the prefix is needed. Usually, the prefix is the sample name.
-            For example, `Sample1-AACGTTGAGGCTACGT-1`.
-            We need this prefix to add the sample name to the cell names in
-            immdata, so that we can match the cells in `immdata` and
-            `Seurat` object. Set it to `None` or an empty string if the
-            `Seurat` object has the same cell names as `immdata`. You can use
-            placeholders to specify the prefix, e.g., `{Sample}_`. In such a
-            case, the `Sample` column must exist in the `Seurat` object.
+            Or simply a list of two groups, for example, `["Treg", "Tconv"]` when
+            they are both in the `group` column.
         target: Which group to use as the target group. The target
             group will be labeled as 1, and the other group will be labeled as
             0 in the regression.
-        subset: A column, or a list of columns separated by comma,
-            in the merged object to subset the cells to perform the regression,
-            for each group in the columns.
+            If not specified, the first group in `comparison` will be used as
+            the target group.
+        each (auto): A column, or a list of columns or a string of columns separated by comma.
+            The columns will be used to split the data into multiple groups and the regression will be
+            applied to each group separately.
             If not provided, all the cells will be used.
     """  # noqa: E501
-    input = "immdata:file,srtobj:file"
+    input = "scrfile:file"
     output = "outdir:dir:{{in.immdata | stem}}.cdr3aaphyschem"
     lang = config.lang.rscript
     envs = {
         "group": None,
         "comparison": None,
-        "prefix": "{Sample}_",
         "target": None,
-        "subset": None,
+        "each": None,
     }
     script = "file://../scripts/tcr/CDR3AAPhyschem.R"
     plugin_opts = {"report": "file://../reports/tcr/CDR3AAPhyschem.svelte"}
@@ -1480,49 +1558,36 @@ class TESSA(Proc):
             [link](https://www.nature.com/articles/s42256-021-00383-2)
 
     Input:
-        immdata: The data loaded by `immunarch::repLoad()`, saved in RDS format
-        srtobj: The `Seurat` object, saved in RDS format, with dimension
-            reduction performed if you want to use them to represent the
-            transcriptome of T cells.
-            This could also be a tab delimited file (can be gzipped) with
-            expression matrix or dimension reduction results.
+        screpdata: The data loaded by `ScRepCombiningExpression`, saved in RDS or
+            qs/qs2 format.
+            The data is actually generated by `scRepertiore::combineExpression()`.
+            The data must have both TRA and TRB chains.
 
     Output:
-        outfile: The tab-delimited file with three columns
-            (`barcode`, `TESSA_Cluster` and `TESSA_Cluster_Size`) or
-            an RDS file if  `in.srtobj` is an RDS file of a Seurat object, with
+        outfile: a qs fileof a Seurat object, with
             `TESSA_Cluster` and `TESSA_Cluster_Size` added to the `meta.data`
 
     Envs:
         python: The path of python with `TESSA`'s dependencies installed
-        prefix: The prefix to the barcodes of TCR data. You can use placeholder
-            like `{Sample}_` to use the meta data from the immunarch object.
         within_sample (flag): Whether the TCR networks are constructed only
             within TCRs from the same sample/patient (True) or with all the
             TCRs in the meta data matrix (False).
         assay: Which assay to use to extract the expression matrix.
             Only works if `in.srtobj` is an RDS file of a Seurat object.
+            By default, if `SCTransform` is performed, `SCT` will be used.
         predefined_b (flag): Whether use the predefined `b` or not.
             Please check the paper of tessa for more details about the b vector.
             If True, the tessa will not update b in the MCMC iterations.
         max_iter (type=int): The maximum number of iterations for MCMC.
         save_tessa (flag): Save tessa detailed results to seurat object?
-            Only works if `in.srtobj` is an RDS file of a Seurat object.
             It will be saved to `sobj@misc$tessa`.
     """
-    input = "immdata:file,srtobj:file"
-    output = """outfile:file:
-        {%- if in.srtobj.lower().endswith(".rds") -%}
-        {{in.srtobj | stem}}.tessa.RDS
-        {%- else -%}
-        {{in.immdata | stem}}.tessa.txt
-        {%- endif -%}
-    """
+    input = "screpdata:file"
+    output = "outfile:file:{{in.screpdata | stem}}.tessa.qs"
     lang = config.lang.rscript
     envs = {
         "python": config.lang.python,
-        "prefix": "{Sample}_",
-        "assay": "RNA",
+        "assay": None,
         "within_sample": False,
         "predefined_b": False,
         "max_iter": 1000,
@@ -1530,3 +1595,523 @@ class TESSA(Proc):
     }
     script = "file://../scripts/tcr/TESSA.R"
     plugin_opts = {"report": "file://../reports/tcr/TESSA.svelte"}
+
+
+class TCRDock(Proc):
+    """Using TCRDock to predict the structure of MHC-peptide-TCR complexes
+
+    See <https://github.com/phbradley/TCRdock>.
+
+    Input:
+        configfile: The config file for TCRDock
+            It's should be a toml file with the keys listed in `envs`, including
+            `organism`, `mhc_class`, `mhc`, `peptide`, `va`, `ja`, `vb`, `jb`,
+            `cdr3a`, and `cdr3b`.
+            The values will overwrite the values in `envs`.
+
+    Output:
+        outdir: The output directory containing the results
+
+    Envs:
+        organism: The organism of the TCR, peptide and MHC
+        mhc_class (type=int): The MHC class, either `1` or `2`
+        mhc: The MHC allele, e.g., `A*02:01`
+        peptide: The peptide sequence
+        va: The V alpha gene
+        ja: The J alpha gene
+        vb: The V beta gene
+        jb: The J beta gene
+        cdr3a: The CDR3 alpha sequence
+        cdr3b: The CDR3 beta sequence
+        python: The path of python with dependencies for `tcrdock` installed.
+            If not provided, `TCRDock.lang` will be used (the same interpreter
+            used for the wrapper script).
+            It could also be a list to specify, for example, a python in a conda
+            environment (e.g., `["conda", "run", "-n", "myenv", "python"]`).
+        tmpdir: The temporary directory used to clone the `tcrdock` source code if
+            `envs.tcrdock` is not provided.
+        tcrdock: The path to the `tcrdock` source code repo.
+            You need to clone the source code from the github repository.
+            <https://github.com/phbradley/TCRdock> at
+            revision c5a7af42eeb0c2a4492a4d4fe803f1f9aafb6193 at main branch.
+            You also have to run `download_blast.py` after cloning to download the
+            blast database in the directory.
+            If not provided, we will clone the source code to the `envs.tmpdir`
+            directory and run the `download_blast.py` script.
+        model_name: The model name to use
+        model_file: The model file to use.
+            If provided as a relative path, it should be relative to the
+            `<envs.data_dir>/params/`, otherwise, it should be the full path.
+        data_dir: The data directory that contains the model files.
+            The model files should be in the `params` subdirectory.
+    """
+    input = "configfile:file"
+    output = "outdir:dir:{{in.configfile | stem}}.tcrdock"
+    lang = config.lang.python
+    envs = {
+        "tcrdock": None,
+        "organism": "human",
+        "mhc_class": 1,
+        "mhc": "A*02:01",
+        "peptide": None,
+        "va": None,
+        "ja": None,
+        "vb": None,
+        "jb": None,
+        "cdr3a": None,
+        "cdr3b": None,
+        "python": None,
+        "model_name": "model_2_ptm_ft4",
+        "model_file": "tcrpmhc_run4_af_mhc_params_891.pkl",
+        "data_dir": None,
+    }
+    script = "file://../scripts/tcr/TCRDock.py"
+
+
+class ScRepLoading(Proc):
+    """Load the single cell TCR/BCR data into a `scRepertoire` compatible object
+
+    This process loads the single cell TCR/BCR data into a `scRepertoire`
+    (>= v2.0.8, < v2.3.2) compatible object. Later, `scRepertoire::combineExpression`
+    can be used to combine the expression data with the TCR/BCR data.
+
+    For the data path specified at `TCRData`/`BCRData` in the input file
+    (`in.metafile`), will be used to find the TCR/BCR data files and
+    `scRepertoire::loadContigs()` will be used to load the data.
+
+    A directory can be specified in `TCRData`/`BCRData`, then
+    `scRepertoire::loadContigs()` will be used directly to load the data from the
+    directory. Otherwise if a file is specified, it will be symbolically linked to
+    a directory for `scRepertoire::loadContigs()` to load.
+    Note that when the file name can not be recognized by `scRepertoire::loadContigs()`,
+    `envs.format` must be set for the correct format of the data.
+
+    Input:
+        metafile: The meta data of the samples
+            A tab-delimited file
+            Two columns are required:
+            * `Sample` to specify the sample names.
+            * `TCRData`/`BCRData` to assign the path of the data to the samples,
+            and this column will be excluded as metadata.
+
+    Output:
+        outfile: The `scRepertoire` compatible object in qs/qs2 format
+
+    Envs:
+        type (choice): The type of the data to load.
+            - TCR: T cell receptor data
+            - BCR: B cell receptor data
+            - auto: Automatically detect the type from the metadata.
+                If `auto` is selected, the type will be determined by the presence of
+                `TCRData` or `BCRData` columns in the metadata. If both columns are
+                present, `TCR` will be selected by default.
+        combineTCR (type=json): The extra arguments for `scRepertoire::combineTCR`
+            function.
+            See also <https://www.borch.dev/uploads/screpertoire/reference/combinetcr>
+        combineBCR (type=json): The extra arguments for `scRepertoire::combineBCR`
+            function.
+            See also <https://www.borch.dev/uploads/screpertoire/reference/combinebcr>
+        exclude (auto): The columns to exclude from the metadata to add to the object.
+            A list of column names to exclude or a string with column names separated
+            by `,`. By default, `BCRData`, `TCRData` and `RNAData` will be excluded.
+        tmpdir: The temporary directory to store the symbolic links to the
+            TCR/BCR data files.
+        format (choice): The format of the TCR/BCR data files.
+            - 10X: 10X Genomics data, which is usually in a directory with
+                `filtered_contig_annotations.csv` file.
+            - AIRR: AIRR format, which is usually in a file with
+                `airr_rearrangement.tsv` file.
+            - BD: Becton Dickinson data, which is usually in a file with
+                `Contigs_AIRR.tsv` file.
+            - Dandelion: Dandelion data, which is usually in a file with
+                `all_contig_dandelion.tsv` file.
+            - Immcantation: Immcantation data, which is usually in a file with
+                `data.tsv` file.
+            - JSON: JSON format, which is usually in a file with `.json` extension.
+            - ParseBio: ParseBio data, which is usually in a file with
+                `barcode_report.tsv` file.
+            - MiXCR: MiXCR data, which is usually in a file with `clones.tsv` file.
+            - Omniscope: Omniscope data, which is usually in a file with `.csv`
+                extension.
+            - TRUST4: TRUST4 data, which is usually in a file with
+                `barcode_report.tsv` file.
+            - WAT3R: WAT3R data, which is usually in a file with
+                `barcode_results.csv` file.
+            See also: <https://rdrr.io/github/ncborcherding/scRepertoire/man/loadContigs.html>
+            If not provided, the format will be guessed from the file name by `scRepertoire::loadContigs()`.
+    """  # noqa: E501
+    input = "metafile:file"
+    output = "outfile:file:{{in.metafile | stem}}.scRep.qs"
+    lang = config.lang.rscript
+    envs = {
+        "type": "auto",  # or TCR/BCR
+        "combineTCR": {"samples": True},
+        "combineBCR": {"samples": True},
+        "exclude": ["BCRData", "TCRData", "RNAData"],
+        "format": None,
+        "tmpdir": config.path.tmpdir,
+    }
+    script = "file://../scripts/tcr/ScRepLoading.R"
+
+
+class ScRepCombiningExpression(Proc):
+    """Combine the scTCR/BCR data with the expression data
+
+    This process combines the scTCR/BCR data with the expression data using
+    `scRepertoire::combineExpression` function. The expression data should be
+    in `Seurat` format. The `scRepertoire` object should be a combined contig
+    object, usually generated by `scRepertoire::combineTCR` or
+    `scRepertoire::combineBCR`.
+
+    See also: <https://www.borch.dev/uploads/screpertoire/reference/combineexpression>.
+
+    Input:
+        screpfile: The `scRepertoire` object in RDS/qs format
+        srtobj: The `Seurat` object, saved in RDS/qs format
+
+    Output:
+        outfile: The `Seurat` object with the TCR/BCR data combined
+            In addition to the meta columns added by
+            `scRepertoire::combineExpression()`, a new column `VDJ_Presence` will be
+            added to the metadata. It indicates whether the cell has a TCR/BCR
+            sequence or not. The value is `TRUE` if the cell has a TCR/BCR sequence,
+            and `FALSE` otherwise.
+
+    Envs:
+        cloneCall: How to call the clone - VDJC gene (gene), CDR3 nucleotide (nt),
+            CDR3 amino acid (aa), VDJC gene + CDR3 nucleotide (strict) or
+            a custom variable in the data.
+        chain: indicate if both or a specific chain should be used
+            e.g. "both", "TRA", "TRG", "IGH", "IGL".
+        group_by: The column label in the combined clones in which clone frequency will
+            be calculated. NULL or "none" will keep the format of input.data.
+        proportion (flag): Whether to proportion (TRUE) or total frequency (FALSE) of
+            the clone based on the group_by variable.
+        filterNA (flag): Method to subset Seurat/SCE object of barcodes without clone
+            information
+        cloneSize (type=json): The bins for the grouping based on proportion or
+            frequency.
+            If proportion is FALSE and the cloneSizes are not set high enough based on
+            frequency, the upper limit of cloneSizes will be automatically updated.
+        addLabel (flag): This will add a label to the frequency header, allowing the
+            user to try multiple group_by variables or recalculate frequencies after
+            subsetting the data.
+    """
+    input = "screpfile:file,srtobj:file"
+    output = "outfile:file:{{in.screpfile | stem}}.qs"
+    lang = config.lang.rscript
+    envs = {
+        "cloneCall": "aa",
+        "chain": "both",
+        "group_by": "Sample",
+        "proportion": True,
+        "filterNA": False,
+        "cloneSize": {
+            "Rare": 1e-04,
+            "Small": 0.001,
+            "Medium": 0.01,
+            "Large": 0.1,
+            "Hyperexpanded": 1,
+        },
+        "addLabel": False,
+    }
+    script = "file://../scripts/tcr/ScRepCombiningExpression.R"
+
+
+class ClonalStats(Proc):
+    """Visualize the clonal information.
+
+    Using [`scplotter`](https://github.com/pwwang/scplotter) to visualize the clonal
+    information.
+
+    Examples:
+        ### Clonal Volume
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Volume"]
+        viz_type = "volume"
+        x_text_angle = 45
+        ```
+
+        ![Clonal_Volume](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Number-of-Clones/Clonal-Volume.png){: width="80%"}
+
+        ### Clonal Volume by Diagnosis
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Volume by Diagnosis"]
+        viz_type = "volume"
+        x = "seurat_clusters"
+        group_by = "Diagnosis"
+        comparisons = true
+        ```
+
+        ![Clonal_Volume_by_Diagnosis](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Number-of-Clones/Clonal-Volume-by-Diagnosis.png){: width="80%"}
+
+        ### Clonal Abundance
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Abundance"]
+        viz_type = "abundance"
+        ```
+
+        ![Clonal_Abundance](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Abundance/Clonal-Abundance.png){: width="80%"}
+
+        ### Clonal Abundance Density
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Abundance Density"]
+        viz_type = "abundance"
+        plot_type = "density"
+        ```
+
+        ![Clonal_Abundance_Density](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Abundance/Clonal-Abundance-Density.png){: width="80%"}
+
+        ### CDR3 Length
+
+        ```toml
+        [ClonalStats.envs.cases."CDR3 Length"]
+        viz_type = "length"
+        ```
+
+        ![CDR3_Length](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Sequence-Length/CDR3-Length.png){: width="80%"}
+
+        ### CDR3 Length (Beta Chain)
+
+        ```toml
+        [ClonalStats.envs.cases."CDR3 Length (Beta Chain)"]
+        viz_type = "length"
+        chain = "TRB"
+        ```
+
+        ![CDR3_Length_Beta_Chain](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Sequence-Length/CDR3-Length-Beta-Chain-.png){: width="80%"}
+
+        ### Clonal Residency
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Residency"]
+        viz_type = "residency"
+        group_by = "Diagnosis"
+        chain = "TRB"
+        clone_call = "gene"
+        groups = ["Colitis", "NoColitis"]
+        ```
+
+        ![Clonal_Residency](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Residency/Clonal-Residency.png){: width="80%"}
+
+        ### Clonal Residency (UpSet Plot)
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Residency (UpSet Plot)"]
+        viz_type = "residency"
+        plot_type = "upset"
+        group_by = "Diagnosis"
+        chain = "TRB"
+        clone_call = "gene"
+        groups = ["Colitis", "NoColitis"]
+        devpars = {width = 800}
+        ```
+
+        ![Clonal_Residency_UpSet_Plot](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Residency/Clonal-Residency-UpSet-Plot-.png){: width="80%"}
+
+        ### Clonal Statistics with Expanded Clones
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Statistics with Expanded Clones"]
+        viz_type = "stat"
+        plot_type = "pies"
+        group_by = "Diagnosis"
+        groups = ["Colitis", "NoColitis"]
+        clones = {"Expanded Clones In Colitis" = "sel(Colitis > 2)", "Expanded Clones In NoColitis" = "sel(NoColitis > 2)"}
+        subgroup_by = "seurat_clusters"
+        pie_size = "sqrt"
+        show_row_names = true
+        show_column_names = true
+        devpars = {width = 720}
+        ```
+
+        ![Clonal_Statistics_with_Expanded_Clones](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Statistics/Clonal-Statistics-with-Expanded-Clones.png){: width="80%"}
+
+        ### Hyperexpanded Clonal Dynamics
+
+        ```toml
+        [ClonalStats.envs.cases."Hyperexpanded Clonal Dynamics"]
+        viz_type = "stat"
+        plot_type = "sankey"
+        group_by = "Diagnosis"
+        chain = "TRB"
+        groups = ["Colitis", "NoColitis"]
+        clones = {"Hyper-Expanded Clones In Colitis" = "sel(Colitis > 5)", "Hyper-Expanded Clones In NoColitis" = "sel(NoColitis > 5)"}
+        devpars = {width = 800}
+        ```
+
+        ![Hyperexpanded_Clonal_Dynamics](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Statistics/Hyperexpanded-Clonal-Dynamics.png){: width="80%"}
+
+        ### Clonal Composition
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Composition"]
+        viz_type = "composition"
+        x_text_angle = 45
+        ```
+
+        ![Clonal_Composition](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Composition.png){: width="80%"}
+
+        ### Clonal Overlapping
+
+        ```toml
+        viz_type = "overlap"
+        chain = "TRB"
+        clone_call = "gene"
+        ```
+
+        ![Clonal_Overlapping](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Overlapping.png){: width="80%"}
+
+        ### Clonal Diversity
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Diversity"]
+        # method = "shannon"  # default
+        viz_type = "diversity"
+        x_text_angle = 45
+        ```
+
+        ![Clonal_Diversity](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Diversity/Clonal-Diversity.png){: width="80%"}
+
+        ### Clonal Diversity (gini.coeff, by Diagnosis)
+
+        ```toml
+        [ClonalStats.envs.cases."Clonal Diversity (gini.coeff, by Diagnosis)"]
+        method = "gini.coeff"
+        viz_type = "diversity"
+        plot_type = "box"
+        group_by = "Diagnosis"
+        comparisons = true
+        devpars = {height = 600, width = 600}
+        ```
+
+        ![Clonal_Diversity_gini_coeff_by_Diagnosis](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Clonal-Diversity/Clonal-Diversity-gini-coeff-by-Diagnosis-.png){: width="80%"}
+
+        ### Gene Usage Frequency
+
+        ```toml
+        [ClonalStats.envs.cases."Gene Usage Frequency"]
+        viz_type = "geneusage"
+        devpars = {width = 1200}
+        ```
+
+        ![Gene_Usage_Frequency](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Gene-Usage-Frequency.png){: width="80%"}
+
+        ### Positional amino acid frequency
+
+        ```toml
+        [ClonalStats.envs.cases."Positional amino acid frequency"]
+        viz_type = "positional"
+        # method = "AA"  # default
+        devpars = {width = 1600}
+        ```
+
+        ![Positional_amino_acid_frequency](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Positional-Properties/Positional-amino-acid-frequency.png){: width="80%"}
+
+        ### Positional shannon entropy
+
+        ```toml
+        [ClonalStats.envs.cases."Positional shannon entropy"]
+        viz_type = "positional"
+        method = "shannon"
+        devpars = {width = 1200}
+        ```
+
+        ![Positional_shannon_entropy](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Positional-Properties/Positional-shannon-entropy.png){: width="80%"}
+
+        ### 3-Mer Frequency
+
+        ```toml
+        [ClonalStats.envs.cases."3-Mer Frequency"]
+        viz_type = "kmer"
+        k = 3  # default is 3
+        devpars = {width = 800}
+        ```
+
+        ![3_Mer_Frequency](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/3-Mer-Frequency.png){: width="80%"}
+
+        ### Rarefaction Curve
+
+        ```toml
+        [ClonalStats.envs.cases."Rarefaction Curve"]
+        viz_type = "rarefaction"
+        ```
+
+        ![Rarefaction_Curve](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/clonalstats/ClonalStats/sampleinfo.scRep.clonalstats/Rarefaction-Curve.png){: width="80%"}
+
+    Input:
+        screpfile: The `scRepertoire` object in RDS/qs format
+
+    Output:
+        outdir: The output directory containing the plots
+
+    Envs:
+        mutaters (type=json;order=-9): The mutaters passed to `dplyr::mutate()` to add new variables.
+            When the object loaded form `in.screpfile` is a list, the mutaters will be applied to each element.
+            The keys are the names of the new variables, and the values are the expressions.
+            When it is a `Seurat` object, typically an output of `scRepertoire::combineExpression()`,
+            the mutaters will be applied to the `meta.data`.
+        viz_type (choice): The type of visualization to generate.
+            - volume: The volume of the clones using [`ClonalVolumePlot`](https://pwwang.github.io/scplotter/reference/ClonalVolumePlot.html)
+            - abundance: The abundance of the clones using [`ClonalAbundancePlot`](https://pwwang.github.io/scplotter/reference/ClonalAbundancePlot.html)
+            - length: The length of the CDR3 sequences using [`ClonalLengthPlot`](https://pwwang.github.io/scplotter/reference/ClonalLengthPlot.html)
+            - residency: The residency of the clones using [`ClonalResidencyPlot`](https://pwwang.github.io/scplotter/reference/ClonalResidencyPlot.html)
+            - stats: The stats of the clones using [`ClonalStatsPlot`](https://pwwang.github.io/scplotter/reference/ClonalStatsPlot.html)
+            - composition: The composition of the clones using [`ClonalCompositionPlot`](https://pwwang.github.io/scplotter/reference/ClonalCompositionPlot.html)
+            - overlap: The overlap of the clones using [`ClonalOverlapPlot`](https://pwwang.github.io/scplotter/reference/ClonalOverlapPlot.html)
+            - diversity: The diversity of the clones using [`ClonalDiversityPlot`](https://pwwang.github.io/scplotter/reference/ClonalDiversityPlot.html)
+            - geneusage: The gene usage of the clones using [`ClonalGeneUsagePlot`](https://pwwang.github.io/scplotter/reference/ClonalGeneUsagePlot.html)
+            - positional: The positional information of the clones using [`ClonalPositionalPlot`](https://pwwang.github.io/scplotter/reference/ClonalPositionalPlot.html)
+            - kmer: The kmer information of the clones using [`ClonalKmerPlot`](https://pwwang.github.io/scplotter/reference/ClonalKmerPlot.html)
+            - rarefaction: The rarefaction curve of the clones using [`ClonalRarefactionPlot`](https://pwwang.github.io/scplotter/reference/ClonalRarefactionPlot.html)
+        subset: An expression to subset the data before plotting.
+            Similar to `mutaters`, it will be applied to each element by `dplyr::filter()` if the object
+            loaded form `in.screpfile` is a list; otherwise, it will be applied to
+            `subset(sobj, subset = <expr>)` if the object is a `Seurat` object.
+        devpars (ns): The parameters for the plotting device.
+            - width (type=int): The width of the device
+            - height (type=int): The height of the device
+            - res (type=int): The resolution of the device
+        more_formats (list): The extra formats to save the plots in, other than PNG.
+        save_code (flag): Whether to save the code used to generate the plots
+            Note that the data directly used to generate the plots will also be saved in an `rda` file.
+            Be careful if the data is large as it may take a lot of disk space.
+        save_data (flag): Whether to save the data used to generate the plot.
+        descr: The description of the plot, used to show in the report.
+        <more>: The arguments for the plot function
+            See the documentation of the corresponding plot function for the details
+        cases (type=json): The cases to generate the plots if we have multiple cases.
+            The keys are the names of the cases, and the values are the arguments for the plot function.
+            The arguments in `envs` will be used if not specified in `cases`, except for `mutaters`.
+            Sections can be specified as the prefix of the case name, separated by `::`.
+            For example, if you have a case named `Clonal Volume::Case1`, the plot will be put in the
+            section `Clonal Volume`. By default, when there are multiple cases for the same 'viz_type', the name of the 'viz_type' will be used
+            as the default section name (for example, when 'viz_type' is 'volume', the section name will be 'Clonal Volume').
+            When there is only a single case, the section name will default to 'DEFAULT', which will not be shown
+            in the report.
+    """  # noqa: E501
+    input = "screpfile:file"
+    output = "outdir:dir:{{in.screpfile | stem}}.clonalstats"
+    lang = config.lang.rscript
+    envs = {
+        "mutaters": {},
+        "subset": None,
+        "viz_type": None,
+        "devpars": {"width": None, "height": None, "res": 100},
+        "more_formats": [],
+        "save_code": False,
+        "save_data": False,
+        "descr": None,
+        "cases": {
+            "Clonal Volume": {"viz_type": "volume"},
+            "Clonal Abundance": {"viz_type": "abundance"},
+            "CDR3 Length": {"viz_type": "length"},
+            "Clonal Diversity": {"viz_type": "diversity"},
+        }
+    }
+    script = "file://../scripts/tcr/ClonalStats.R"
+    plugin_opts = {"report": "file://../reports/tcr/ClonalStats.svelte"}