SingleRepExplorer Manual

1. About

SingleRepExplorer is an interactive web application, built using the R/Shiny framework, designed for the comprehensive analysis of single-cell immune profiling data. It addresses the significant challenge of integrating single-cell RNA sequencing (scRNA-seq) transcriptomics with paired T-cell receptor (TCR) and B-cell receptor (BCR) repertoire analysis.

The tool is specifically designed to be accessible to biologists and researchers who may have limited bioinformatics or command-line expertise. It provides a user-friendly graphical interface that streamlines complex analytical workflows, from data input to publication-ready visualizations.

Core Functionalities

1. Data Input and Processing:
   • Accepts standard output files from 10x Genomics Cell Ranger (e.g., filtered_feature_bc_matrix.h5 and filtered_contig_annotations.csv).
   • Performs an automated workflow upon data upload, including normalization, scaling, clustering, and non-linear dimensionality reduction (UMAP/t-SNE) using the Seurat package.
2. Transcriptome Analysis:
   • Visualization: Offers interactive UMAP, violin plots, and feature plots to explore gene expression.
   • Annotation: Facilitates automated cell typing (e.g., via scType) and allows users to explore marker genes.
   • Differential Expression: Identifies differentially expressed genes (DEGs) between user-defined cell groups.
3. Immune Repertoire Analysis:
   • Integration: Seamlessly combines TCR/BCR contig information with the scRNA-seq data using the scRepertoire package.
   • Basic Characterization: Provides modules to analyze clonal frequency, abundance, CDR3 length distribution, and repertoire diversity (e.g., Alpha diversity).
   • Comparative Analysis: Includes tools for assessing clonal overlap between samples, identifying “public” clonotypes shared across groups, and tracking the dynamics of specific clones.
   • Advanced Features: Offers specialized analyses such as:
     • Antigen Prediction: Predicts potential antigens for specific TCR clonotypes.
     • BCR Analysis: Visualizes isotype usage (e.g., IGHM, IGHG1) and constructs phylogenetic trees to explore clonal evolution and somatic hypermutation.

By integrating these diverse functionalities into a single workbench, SingleRepExplorer significantly reduces the time and effort required for analysis, empowering researchers to interactively explore and interpret complex single-cell immune profiling datasets.

2. Getting Started

SingleRepExplorer is distributed as a Docker container, making it easy to run on any system (Windows, macOS, or Linux). The only prerequisite is to have Docker Desktop installed.

Step 1: Install Docker Desktop

If you do not already have it, please install Docker Desktop. It is a free application for Mac and Windows.

• Download for macOS: https://www.docker.com/products/docker-desktop/
• Download for Windows: https://www.docker.com/products/docker-desktop/

After installing, please start the Docker Desktop application. You must have it running in the background to proceed.

Step 2: Run SingleRepExplorer

Once Docker is running, open your command-line terminal.

• On macOS: Open the “Terminal” app (you can find it in Applications/Utilities).
• On Windows: Open “PowerShell” or “Command Prompt” (you can find it in the Start Menu).

Copy and paste the following command into your terminal, then press Enter:

docker run --rm -p 3838:3838 amufaamo/singlerepexplorer:latest

This command will automatically:

1. Download (pull) the amufaamo/singlerepexplorer:latest image from Docker Hub, if you don’t have it.
2. Start the application.

• --rm: This flag ensures the container is automatically removed when you stop it.
• -p 3838:3838: This maps port 3838 on your computer (localhost) to the application’s port 3838 inside the container.

Step 3: Access the Application

The application is now running. Open your web browser (like Chrome, Firefox, or Safari) and navigate to the following address:

http://localhost:3838

You should now see the SingleRepExplorer interface and can begin your analysis.

Stopping the Application

To stop the application, simply return to your terminal window where the command is running and press Ctrl+C.

3. Data Upload and Processing

The first step in using SingleRepExplorer is to upload your dataset via this tab. The application is designed to process outputs from the 10x Genomics Cell Ranger pipeline.

1. Files to Upload

You must upload the gene expression data, and you can optionally provide TCR and/or BCR repertoire files.

• 1. Choose .h5 file (Required)
  • Upload the filtered_feature_bc_matrix.h5 file. This contains the core single-cell gene expression data and is mandatory for all analyses.
• 2. Choose .tcr file (Optional)
  • Upload the filtered_contig_annotations.csv file for the T-cell receptor (TCR) repertoire. This is required if you wish to perform TCR analysis.
• 3. Choose .bcr file (Optional)
  • Upload the filtered_contig_annotations.csv file for the B-cell receptor (BCR) repertoire. This is required for BCR analysis.

After selecting a file, a green “✅ Uploaded!” status message will appear beside the button to confirm the upload.

2. Running the Analysis

1. Analysis Start (Custom Data):
   • Once you have uploaded the necessary files, click the blue [Run] button.
   • This initiates the analysis pipeline on your uploaded data.
2. Analysis Start (Demo Data):
   • If you want to try the application without uploading files, click the blue [Demo Data] button.
   • This will automatically load the provided example dataset and run the analysis.
   • Note: The [Demo Data] button is located below the [Run] button.
3. Analysis Workflow (Background):
   • When an analysis starts (via Run or Demo Data), the buttons are temporarily disabled.
   • A status message appears: “🏃 Starting analysis…”.
   • A progress bar titled “Analysis in progress” shows the current step:
     • Loading .h5 file...
     • Running Seurat object... (Normalization, Scaling, PCA, UMAP/t-SNE)
     • Adding cell types...
     • Processing TCR/BCR data...
   • Upon completion, a “🎉 Analysis finished successfully!” message appears, and the buttons are re-enabled.

Error Handling: If you click [Run] without searching for or uploading the mandatory .h5 file, an alert box will appear.

---

This section provides a detailed guide to the various analysis tabs available in SingleRepExplorer.

4. Dimensional Plot

This tab is the primary interface for visualizing your clustered single-cell data. It allows you to explore cell populations on a 2D map (like UMAP or t-SNE) and interact with the data by coloring, renaming, and highlighting specific cell groups.

The tab is divided into a Sidebar Panel (left) for controls and a Main Panel (right) for outputs.

Sidebar Panel: Controls

The sidebar contains all the options to customize your plot.

1. Plot Display Options

• Reduction: Select the dimensionality reduction method to display. This is typically UMAP or TSNE. The dropdown is populated automatically from your loaded Seurat object.
• Group by: This is a key control. Choose which metadata column to use for coloring the cells (e.g., seurat_clusters, sample, or any custom cell type annotations).
• Rename (Button): Click this button to rename or regroup the categories in your selected “Group by” column.
  • A pop-up window will appear.
  • Enter a New Group Name (e.g., Celltype_manual).
  • For each existing level (e.g., Cluster “0”), you can provide a new name (e.g., “T-cells”). You can assign the same new name to multiple old levels to merge them.
  • Click “Save”, and this new grouping will be added to your dataset and automatically selected in the “Group by” dropdown.
• Point Size: Adjusts the size of the individual dots on the plot.
• Label Size: Adjusts the size of the text labels for each cluster.
• Legend Position: Control where the plot legend is placed (or set to “none”).
• Plot Width / Height: Adjust the dimensions of the plot in pixels.

---

2. Search & Highlight

This powerful feature allows you to find specific cells based on complex criteria (including repertoire data) and highlight them on the plot.

1. Enable Highlight by Search: Check this box to activate the feature. This will temporarily override the “Group by” coloring.
2. Select Data Source: Choose where to search for your cells:
   • Seurat Metadata: Search any categorical column in the main Seurat object (e.g., seurat_clusters, sample).
   • TCR Clonotypes: (If loaded) Search the TCR data table.
   • BCR Clonotypes: (If loaded) Search the BCR data table.
3. Select Column to Search: Based on your source, select a column to search (e.g., raw_clonotype_id from TCR data, or seurat_clusters from Metadata).
4. Select Value(s) to Highlight: Type or select one or more values from the chosen column (e.g., a specific clonotype ID like “clonotype10”).
5. Apply Highlight: Click this button. The plot will update to show all cells matching your criteria in dark blue, while all other cells will be greyed out.

To return to the “Group by” cluster view, simply uncheck the “Enable Highlight by Search” box.

Main Panel: Outputs

1. Plot

This area displays the dimensional reduction plot you have configured. * Download plot (.pdf): Click to download the current plot as a high-resolution, publication-ready PDF.

2. Coordinates Table

This is an interactive table showing the underlying data for the plot. * It displays the selected “Group by” information (e.g., seurat_clusters) and the X/Y coordinates (e.g., UMAP_1, UMAP_2) for every cell. * Download Table (.csv): Click to download this full data table as a CSV file.

[Transcriptome] Tab

This tab contains modules for exploring gene expression patterns and performing differential expression analysis.

Expression Visualization

This module allows you to visualize the expression levels of specific genes across your single-cell dataset.

Sidebar Panel: Controls

1. Plot & Gene Selection:
   • Plot type: Select the type of visualization (Feature plot, Violin plot, Dot plot, Heatmap).
   • Enter or select gene names: Type or select gene names (e.g., CD3E).
2. Plot-Specific Options:
   • Group by: Select metadata to group cells by.
   • Reduction: (Feature plot) Select UMAP or TSNE.
   • Point Size, Plot Width/Height: Adjust visuals.

Main Panel: Outputs

• Plot: Displays the gene expression plot.
• Download plot (.pdf): Download the current plot.

Differential Expression

This module allows you to perform Differential Gene Expression (DGE) analysis.

Sidebar Panel: Controls

1. Analysis Setup:
   • Comparison Type:
     • “To entire dataset”: Finds markers for each group vs. all others.
     • “Between selected group(s)”: Compares two specific groups directly.
   • Group by: Select the metadata column defining groups.
   • Log fold change (Threshold): Minimum log-fold change.
   • Minimum percentage (min.pct): Minimum percentage of cells expressing the gene.
   • Run: Start the calculation.
2. Mode-Specific Options:

If “Comparison Type” is “To entire dataset”:

• Show Features:
  • Only Up-regulated: Returns only genes that are higher in the group of interest.
  • Only Down-regulated: Returns only genes that are lower in the group of interest.
  • Both: Returns all differentially expressed genes.
• Number of markers: (Appears after “Run”) The number of top markers to display in the summary table (e.g., 10).
• Threshold of adjusted p-value: (Appears after “Run”) The p-value cutoff for the summary table.

If “Comparison Type” is “Between selected group(s)”:

• Target cluster(s): Select the group(s) you are interested in (this is ident.1 in the comparison).
• Reference cluster(s): Select the group(s) you want to compare against (this is ident.2).
• Highlight Genes: (Appears after “Run”) Enter a comma-separated list of gene names (e.g., CD8A, GZMB) to highlight them on the volcano plot.
• Plot Customization: (Appears after “Run”) Adjust p-value thresholds, point sizes, and plot dimensions.

---

Main Panel: Outputs

• If “To entire dataset”:
  • Markers Table: Summary of top markers for each cluster.
  • All Features Table: Complete DGE results table.
• If “Between selected group(s)”:
  • Volcano Plot: Log-fold change vs. p-value.
  • Results Table: Complete DGE results for the comparison.

---

[Repertoire] Tab

This tab provides a suite of tools for in-depth analysis of immune repertoires.

Clonotype Information

This tab serves as the primary data browser for your repertoire. It provides a comprehensive, filterable table of every unique clonotype identified in your dataset, along with all associated V(D)J gene usage and sequence information.

Sidebar Panel: Controls

• VDJ Type: This is the only control. You must select whether you want to inspect the TCR or BCR clonotype table. The main panel will update based on this selection.

Main Panel: Outputs

• Clonotype Data Table: This powerful, interactive table displays the detailed annotation for each unique clonotype.
  • Filtering: You can type in the search boxes at the top of each column to filter the entire table. For example, you can search for a specific TCR_TRA_v_gene or raw_clonotype_id.
  • Sorting: The table is sorted by default based on the clonotype ID (raw_clonotype_id) to group related subclones together. You can also click any column header to re-sort.
  The table contains extensive information, including:
  • Clonotype IDs: raw_clonotype_id, exact_subclonotype_id.
  • Paired Sequences: CTgene (V/J genes), CTaa (CDR3 amino acid), CTnt (CDR3 nucleotide).
  • Chain 1 (TRA or IGH) Details: V, D (if applicable), J, and C genes.
  • Chain 2 (TRB or IGL/K) Details: V, D (if applicable), J, and C genes.
  • Full Sequences: All framework (FWR) and complementarity-determining regions (CDR) for both nucleotide and amino acid sequences of each chain.
• Download table (.csv): Click this button to download the complete data table (respecting the “TCR” or “BCR” selection) as a CSV file for further analysis.

Frequency Analysis

This versatile module allows you to analyze and visualize the frequencies of two different targets: 1. Clonotype Frequency: (e.g., the “Top 10” most abundant clonotypes) 2. Gene Usage: (e.g., the usage frequency of different V-genes)

Sidebar Panel: Controls

1. Main Setup

• Analysis Target: This crucial toggle switches the entire module’s function.
  • Clonotype Frequency: Analyzes the abundance of the most frequent clonotypes (e.g., “clonotype1”, “clonotype2”).
  • Gene Usage: Analyzes the abundance of specific gene segments (e.g., TRBV6-5, TRAV8-1).
• VDJ Type: Select whether to analyze TCR or BCR data.
• Group by: Choose the metadata column used to group the cells (e.g., sample, seurat_clusters).

2. Mode-Specific Options

The options here change based on your “Analysis Target” selection.

• If “Clonotype Frequency” is selected:
  • Top N Clonotypes: Specify how many of the most abundant clonotypes you want to display (e.g., 10).
• If “Gene Usage” is selected:
  • Target Gene Column: Select the specific gene segment you want to analyze. The choices update based on your VDJ Type (e.g., TCR_TRB_v_gene, BCR_IGH_c_gene, or combined V-J pairs like TCR_TRA_v_j_pair).

3. Plot & Display Options

• Plot Type: Choose the visualization style:
  • Barplot (Dodged): Shows groups side-by-side for each item (clonotype/gene).
  • Barplot (Stacked): Stacks groups on top of each other for each item.
  • Barplot (Normal): (Clonotype Frequency only) Shows a single bar for each clonotype, representing its total frequency across all filtered groups.
  • Heatmap: Displays a matrix of groups vs. items, with color intensity representing frequency.
• Display Value: Toggles the Y-axis (or color for heatmap).
  • Count: Shows the raw number of cells.
  • Percentage: (Important) This logic changes based on the plot type:
    • For Stacked, Dodged, and Heatmap: Shows the percentage within that group (e.g., 5% of “Sample A” uses this gene).
    • For Normal plots: Shows the percentage of the total filtered dataset (e.g., “clonotype1” makes up 2% of all cells).
• Filter Groups: A list of checkboxes will appear based on your “Group by” selection (e.g., all samples). You can uncheck groups to exclude them from the analysis.
• Sort X-axis by group: (Dodged plots only) Choose which group’s value (or “Overall”) should be used to sort the X-axis (clonotypes/genes) from highest to lowest.
• Horizontal Barplot: (Barplot types only) Toggles the bar plots from vertical to horizontal.
• Common Plot Options: Adjust the Plot Width, Plot Height, and Legend Position.

Main Panel: Outputs

• Plot: Displays the configured bar chart or heatmap.
  • Download plot (.pdf): Click to download the visualization as a publication-ready PDF.
• Table: Shows the summary data table used to generate the plot, with exact counts and percentages.
  • Download table (.csv): Click to download this summary data as a CSV file.

Unique Clones

This module helps quantify the diversity of your repertoire by answering the question: “How many different types of clonotypes exist within each group?”

It generates a bar chart showing the total count (or proportion) of unique clonotypes found within each user-defined group (e.g., sample, cluster).

Sidebar Panel: Controls

• VDJ Type: Select whether to analyze TCR or BCR data.
• Group by: Choose the metadata column used to group the cells (e.g., sample, seurat_clusters). The analysis will count unique clonotypes per group.
• Value Type: Choose what the Y-axis of the bar chart represents:
  • Count: Shows the absolute number of unique clonotypes in that group (e.g., “Cluster 1 has 500 unique clonotypes”).
  • Percentage: Shows the proportion of unique clonotypes relative to the total number of cells in that group (e.g., “In Cluster 1, 10% of cells are unique clonotypes”).
• Common Plot Options: Adjust the plot dimensions (Plot Width, Plot Height) and the legend position.

Main Panel: Outputs

• Plot: A bar chart where each bar represents a group (from your “Group by” selection). The height of the bar shows either the total count or the proportion of unique clonotypes, based on your “Value Type” selection.
  • Download plot (.pdf): Downloads the bar chart as a publication-ready PDF.
• Table: An interactive data table showing the summary data used to generate the plot. It includes:
  • Group: The categories from your “Group by” selection.
  • unique_clonotype_count: The absolute number of unique clonotypes.
  • total_clonotype_count: The total number of cells (barcodes) in that group.
  • proportion_unique: The calculated percentage (unique / total).
  • Download table (.csv): Downloads this summary table as a CSV file.

Clonal Abundance

This module visualizes the clonal abundance distribution for each group. It plots the abundance (either as a proportion or raw count) of each clonotype against its rank within its group. This type of plot is useful for assessing clonal dominance and evenness – for example, a steep drop-off indicates that a few clones dominate the repertoire, while a flatter curve suggests a more even distribution.

Sidebar Panel: Controls

• VDJ Type: Select whether to analyze TCR or BCR data.
• Group by: Choose the metadata column used to group the cells (e.g., sample, seurat_clusters). The plot will show a separate line for each group.
• Y-Axis Unit: Choose what the Y-axis represents:
  • Percentage: Shows the proportion of each clonotype relative to the total number of cells within that group.
  • Count: Shows the raw number of cells for each clonotype.
• Filter Groups: A list of checkboxes will appear based on your “Group by” selection. You can uncheck groups to exclude them from the analysis and plot.
• Common Plot Options: Adjust the Plot Width, Plot Height, and Legend Position.

Main Panel: Outputs

• Plot: Displays a rank-abundance plot.
  • X-axis: Shows the rank of the clonotypes within each group (log scale), ordered from most abundant (rank 1) to least abundant.
  • Y-axis: Shows the abundance of the clonotype at that rank, either as a percentage or count, based on your selection.
  • Color: Each line represents a different group defined by your “Group by” selection.
  • Download plot (.pdf): Downloads the rank-abundance plot as a publication-ready PDF.
• Table: An interactive data table showing the data used for the plot. It includes:
  • The grouping column (e.g., sample).
  • raw_clonotype_id: The identifier for each clonotype.
  • count: The raw number of cells for that clonotype in that group.
  • proportion: The calculated proportion of that clonotype within its group.
  • rank: The rank of that clonotype within its group based on abundance.
  • Download table (.csv): Downloads this summary data as a CSV file.

Clonal Length

This module analyzes the length distribution of specific repertoire sequences, most commonly the CDR3. It allows you to visualize and compare whether different cell groups (e.g., samples or clusters) have different characteristic lengths for their receptor sequences.

Sidebar Panel: Controls

• VDJ Type: Select whether to analyze TCR or BCR data.
• Target Column (for Length Calculation): This is the key control. Select the sequence you wish to measure. The choices update based on your VDJ Type.
  • For TCR, you can select TCR_TRB_cdr3 (amino acid length) or TCR_TRB_cdr3_nt (nucleotide length), among other chain options.
  • For BCR, you can select BCR_IGH_cdr3, BCR_IGK_cdr3, etc.
• Group by: Choose the metadata column used to group the cells (e.g., sample, seurat_clusters). The plot will show a separate distribution for each group.
• Filter Groups: A list of checkboxes will appear based on your “Group by” selection. You can uncheck groups to exclude them from the analysis.
• Plot Type: Choose the visualization style:
  • Dodged Bars: Shows the distribution for each group side-by-side. Ideal for comparing specific length counts.
  • Stacked Bars: Stacks the group distributions. Ideal for comparing the proportion of lengths across groups.
  • Boxplot: Visualizes the statistical summary (median, quartiles, range) of lengths for each group.
• Display Value (Bar plots only):
  • Count: The Y-axis shows the raw number of cells for each length.
  • Percentage (%): The Y-axis shows the percentage within that group (e.g., in “Sample A”, 20% of cells have a CDR3 length of 15).
• Horizontal Barplot (Bar plots only): Toggles the bar plots from vertical to horizontal.
• Common Plot Options: Adjust the Plot Width, Plot Height, and Legend Position.

Main Panel: Outputs

• Plot: Displays the configured bar chart or boxplot showing the length distributions.
  • Download plot (.pdf): Click to download the visualization as a publication-ready PDF.
• Table: An interactive data table showing the summary data used to generate the bar charts. It lists each group, each observed sequence length, the raw count, and the calculated percentage. (Note: The boxplot uses the non-summarized raw length data).
  • Download table (.csv): Click to download this summary data as a CSV file.

Track Clonotype

This powerful module allows you to track the abundance of specific, user-selected clonotypes across different groups (e.g., samples, clusters, or time points). It is ideal for visualizing how particular clones expand, contract, or are shared between populations.

This module can generate two types of visualizations: a Stacked Bar chart or an Alluvial Plot.

Sidebar Panel: Controls

• VDJ Type: Select whether to analyze TCR or BCR data.
• Clone Identifier Column: Choose which column to use for identifying clonotypes. This is a crucial setting.
  • e.g., raw_clonotype_id, TCR_pair_CTaa (for paired CDR3 amino acids), or BCR_IGH_cdr3.
• Target Clonotypes: Based on your column selection, this box allows you to select one or multiple clonotypes from the list that you wish to track.
• Group by: Choose the metadata column that defines your groups for tracking (e.g., sample, seurat_clusters).
• Plot Type: Select the visualization style:
  • Stacked Bar: Shows a bar for each group, where each segment’s height represents the abundance of a tracked clonotype.
  • Alluvial Plot: Shows the “flow” of the tracked clonotypes from one group to the next. This is excellent for visualizing changes across ordered groups (like time points).
• Value Type: Toggles the Y-axis.
  • Frequency (%): Shows the clonotype’s abundance as a percentage within that group’s total cells.
  • Count: Shows the raw cell count for that clonotype in that group.
• Group Order: Enter a comma-separated list to define the exact order of the groups on the X-axis (e.g., Sample_A, Sample_B, Sample_C). This is essential for Alluvial plots.
• Legend/Plot Options: Adjust the legend position, plot width, and plot height.
• Download Buttons: Buttons to download the generated plot and the underlying data table.

Main Panel: Outputs

• Clonotype Tracking Plot: Displays the Stacked Bar or Alluvial plot.
  • Stacked Bar: Useful for seeing the relative contribution of each tracked clone to each group.
  • Alluvial Plot: Useful for seeing the “flow” and proportional changes of specific clones as they move between groups.
  • Download plot (.pdf): Downloads the visualization as a publication-ready PDF.
• Tracking Results Table: An interactive data table showing the raw data for the plot. It lists each tracked clonotype, each group, its raw count (n), the total cells in that group (total_n), and its calculated frequency (frequency).
  • Download table (.csv): Downloads this summary data as a CSV file.

Clonal Overlap

This module is used to compare the similarity between the repertoires of different groups. It calculates an “overlap coefficient” for every pair of groups and displays the results as a heatmap, allowing you to quickly see which groups share the most clonotypes.

Sidebar Panel: Controls

• VDJ Type: Select whether to analyze TCR or BCR data.
• Clone Identifier Column: This is a key setting. You must define what constitutes a “clonotype” for the overlap calculation.
  • e.g., TCR_pair_CTaa (paired CDR3 amino acid sequence), raw_clonotype_id, or BCR_IGH_cdr3.
• Group by: Choose the metadata column that defines the groups you want to compare (e.g., sample, seurat_clusters). You must have at least two groups to perform an analysis.
• Common Plot Options: Adjust the Plot Width, Plot Height, and Legend Position.

Main Panel: Outputs

• Plot: This panel displays a heatmap of the overlap scores.
  • Both the X-axis and Y-axis list the groups you selected (e.g., “Sample A”, “Sample B”).
  • Each tile’s color (and the number inside it) represents the overlap coefficient between the two corresponding groups.
  • Calculation: The value is the Overlap Coefficient (Szymkiewicz–Simpson coefficient), which is calculated as: (Number of shared clonotypes) / (Size of the smaller repertoire)
  • A value of 1.0 (darkest color) means 100% overlap. The diagonal will always be 1.0, as a group perfectly overlaps with itself.
  • A value of 0.0 (lightest color) means the two groups share no clonotypes.
  • Download plot (.pdf): Click to download the heatmap as a publication-ready PDF.
• Table: An interactive data table showing the raw matrix of overlap coefficients used to generate the plot.
  • The rows and columns represent the groups, and the cells contain the calculated overlap values (rounded to 3 decimal places).

Public Clonotype

This module helps identify “public clonotypes” – clonotypes that are shared across two or more different groups (e.g., samples, clusters). It visualizes the overlap using a Venn diagram and allows you to inspect the details of the clonotypes found in specific intersections.

Sidebar Panel: Controls

• VDJ Type: Select whether to analyze TCR or BCR data.
• Group by: Choose the metadata column that defines the groups you want to compare (e.g., sample, seurat_clusters).
• Select groups to compare: (Appears after selecting “Group by”) This multi-select dropdown allows you to choose 2 to 4 groups from your dataset to compare in the Venn diagram. Choosing more than 4 groups can make the diagram difficult to interpret.
• Table Value Unit: Choose how the abundance data is displayed in the details table (see Main Panel):
  • Count & Proportion: Show both raw cell counts and proportions.
  • Count: Show only raw cell counts.
  • Proportion: Show only the proportion within each group.
• Common Plot Options: Adjust the Plot Width and Plot Height for the Venn diagram area.

Main Panel: Outputs

• Public Clonotypes Venn Diagram: Displays a Venn diagram illustrating the overlap of unique clonotypes (raw_clonotype_id) between the selected groups.
  • Each circle represents a group.
  • The numbers indicate the count of unique clonotypes found exclusively in that section (either specific to one group or shared only by the groups in that intersection).
• Clonotype Details:
  • Select intersection to inspect: This dropdown menu lists all possible intersections shown in the Venn diagram (including sections unique to a single group). The number of unique clonotypes in each section is shown in parentheses. Select the intersection you want to investigate further.
  • Clonotype Table: This interactive data table displays detailed information about the clonotypes found only in the selected intersection.
    • raw_clonotype_id: The identifier of the public clonotype.
    • Subsequent columns show the abundance (count and/or proportion, based on your sidebar selection) of that specific clonotype within each of the originally selected groups.