Applied Bioinformatics Laboratory@CGBS

ShinySC is a desktop application designed for analyzing scRNA-seq data and automatically annotating cell types.

1. Installing ShinySC

Mac & Linux

1. Install Docker Desktop (link)

2. Pull the shinysc image

3. Run a new container

   

   4. Wait until the service is ready and access the ShinySC via the link

   

   5. ShinySC GUI interface

   

   6. Stop, Restart , and Delete ShinySC container

      

2. Implementation

2-1 The framework of ShinySC

ShinySC consists of nine modules: (1) Data Upload, which supports a wide range of input formats; (2) Quality Control, enabling filtering of cells and genes based on customizable thresholds; (3) Feature Selection and Dimension Reduction, identifying highly variable genes and applying PCA, UMAP, or t-SNE for visualization; (4) Clustering, using graph-based algorithms with adjustable resolution settings and visual outputs; (5) Gene Marker Identification, detecting cluster-specific markers; (6) Automatic Cell Type Annotation, integrating reference-based, marker-based, and GPT-4-based strategies for label assignment; (7) Batch Correction, removing batch effects for integrated analysis across datasets; (8) Differential Gene Expression, allowing comparisons between cell clusters or experimental conditions; and (9) Trajectory Inference, reconstructing dynamic developmental or differentiation pathways.

2-2 Input

2-3 Quality Control

Performing QC involves filtering out low-quality cells based on the number of genes detected (Gene Count), the number of UMIs (Count Depth), and the percentage of mitochondrial gene expression (Mito. gene expression). Visualization tools like violin plots help determine appropriate filtering thresholds.

In addition to violin plots, ShinySC provides histograms to visualize distributions of detected gene content across cells, identify outliers, aid in setting filtering thresholds, and offer a clear overview of QC metrics. ShinySC also includes filters with dynamic dash lines to indicate the filtering range, helping users determine appropriate thresholds for filtering out undesirable cells. Filtered cells are faded out in grey for clarity.

2-4 Feature Selection

Once QC is completed, the data undergoes normalization, variable feature identification, and scaling for subsequent analyses. ShinySC offers two normalization methods: LogNormalize and SCTransform.

Feature selection involves choosing the most variable genes based on expression, retaining meaningful biological information, and excluding random noise. This preserves significant structure and improves computational efficiency for further analysis.

After selecting the most variable genes to retain meaningful biological information and reduce noise, the resulting gene set undergoes PCA. This reduces dimensionality, captures the main sources of variation, and makes subsequent analysis more efficient and insightful.

Seurat's FindClusters function allows for iterative refinement of the resolution parameter for cell clustering. However, Seurat lacks built-in visualization tools to explore cluster changes across resolutions. ShinySC compensates for this by incorporating Clustree, which visualizes cluster evolution across different resolutions ①, ensuring the selection of the most appropriate resolution for subsequent step of clustering②③.

2-5 Clustering

Following initial data processing steps such as normalization, scaling, feature selection, PCA, and clustering, UMAP and t-SNE are key non-linear dimensionality reduction techniques for visualizing complex gene expression patterns in scRNA-Seq data. They help researchers understand cellular composition and heterogeneity. ShinySC offers both UMAP and t-SNE visualizations with interactive features for toggling labels and adjusting label size, plot width, and height.

2-6 Find Gene Markers

FindAllMarkers is a function in the Seurat package designed to identify marker genes that distinguish each cluster in single-cell RNA-seq data by performing differential expression testing and identifying genes significantly expressed in one cluster compared to all others.

ShinySC provides a GUI for FindAllMarkers, enabling users to select differential expression tests from a drop-down menu①， toggle positive markers on/off②, set thresholds for minimum cell expression fraction and log fold change③④,and use a slider to select the top N markers per cluster ⑤.

An interactive table ⑥ with filtering and sorting functionalities displays all gene markers identified by Seurat's FindAllMarkers⑨. A dedicated table ⑦ presents the top N gene markers for each cluster. These markers are selectively filtered based on the percentage difference ④ in gene expression between clusters and ranked by average log fold change (avg_logFC). This table is dynamically connected to a UMAP visualization ⑧, showing marker gene expression levels in each cell cluster.

In addition to the interactive table, ShinySC features dot matrices ⑩ that offer a clear and intuitive visual representation of potential gene markers across different clusters.

Users can customize the k-value ⑪, adjust column and row label sizes, rotate label text, and modify the display's width and height to further enhance the visualization of expression patterns and gene markers ⑫.

2-7 Automatic cell-type annotation

Manual cell-type annotation is time-consuming, error-prone, and dependent on researcher expertise. In contrast, automatic annotation can process thousands of cells in minutes, delivering consistent, reproducible results. ShinySC integrates tools like ScType, scCATCH, SingleR and GPTCelltype, streamlining the annotation process. This allows researchers to obtain accurate, data-driven insights and focus on higher-level analysis and biological discovery, bypassing the tedious task of manual annotation.

2-7-1 Marker-Based Annotation

ShinySC provides a selective drop-down menu ① enabling users to choose the appropriate tissue type for their samples. Beyond integrating the exclusive display function from the ScType command-line R package ②③, ShinySC also offers tables ④ and charts ⑤ that summarize cell-type specific marker genes and their distribution, complementing ScType's capabilities.

While scCATCH allows selection of tissue combinations for annotation, it lacks an interface for selecting gene markers from 353 cell types across 184 tissue types. To enhance usability, ShinySC uses cascade filters ①② for streamlined gene marker selection and provides an interactive table categorizing reference-supported markers ③ .

ShinySC features a radio button ④ to choose between Seurat's FindAllMarkers and scCATCH's algorithm for identifying highly expressed gene markers. The identified cell-type-related markers ⑤ are displayed with supported references (PubMed IDs)⑥, highlighted in UMAP visualizations, and their expression levels shown across cell types ⑦.

2.7.2 Reference-based annotation

ShinySC have streamlined SingleR analysis by adding a simple drop-down menu to select either human or mouse datasets, along with their corresponding references. This minimizes manual matching, reduces errors, and saves time. By linking each organism to the right reference, cell-type annotation becomes faster and more accessible for users of all experience levels.

2.7.3 GPT-based annotation

Despite GPT-4's capability to accurately annotate cell types using marker gene information, the standard single-cell RNA-seq workflow for identifying these markers is missing in the GPTCelltype package. ShinySC ensures completeness by providing the full workflow up to the FindAllMarkers step ①②, making the entire process seamless and comprehensive.

After identifying gene markers for each cluster ②, users can click the "Annotate with GPT-4o" button ③ to perform cell type annotation. Note that GPTCelltype requires an OpenAI API key ④ for this function ⑤⑥⑦. We recommend using the desktop version of ShinySC and advise against sharing your API key or uploading it to public spaces to ensure security.

2.7.4 Summary of Cell-Type Annotations Across Annotation Packages

ShinySC provides a way to compare cell-type annotations from different methods, such as ScType, scCATCH, SingleR and GPTCelltype in a single platform. By integrating diverse approaches, it helps users cross-check classifications and get a clearer picture of cell identities ①. This makes it a useful tool for ensuring more reliable single-cell analysis.

ShinySC’s interactive summary table aggregates annotation results ② (e.g., SingleR, scCATCH) and includes an editable “Custom_Label” column ③. Double‐click to rename clusters, instantly updating UMAP plots. This streamlines label reconciliation and exporting final annotations.

2-8 Batch Effect Correction

The Batch Effect Correction module is accessed by clicking its icon in the left‐side toolbar ①. Checking the “Use Demo Files” box ② automatically loads example PBMC datasets, enabling a quick test of the multiple datasets integration workflow. After uploading your own files or selecting these demos, clicking “Start Analysis with Uploaded Files” or “Start Analysis with Demo Files” ③ initiates processing and displays both unintegrated and integrated UMAP plots. ShinySC integrates datasets using Seurat’s FindIntegrationAnchors() and IntegrateData(), reducing batch effects and aligning cell populations, as visualized in the integrated UMAP ④. Finally, click “Download Integrated Data” ⑤ to obtain the batch‐corrected Seurat object (.rds), ready for further exploration in R or other tools.

2-9 Packages incorporated in ShinySC

2-10 Benchmarking and Performance Assessment

A total of 320k human PBMCs for GEM-X Flex, utilizing a 16-plex sub-pooling strategy, were obtained from 10x Genomics. For benchmarking, we analyzed subsets of 200k, 100k, 80k, 40k, 20k, 10k, and 2k cells to evaluate performance across different input sizes.

3. Examples of Use

To demonstrate the functionalities of ShinySC, two publicly available single-cell RNA-seq datasets were analyzed.

3-1 Example 1 - Core Workflow Demonstration

3-1-1 Data upload

For convenient testing of ShinySC with a demonstration dataset, users can visit web version of  ShinySC . Navigate to the "Data Upload" panel ①, select the "Use Demo" checkbox ②, and click "Load Demo" under Example 1 ③. Then, launch the Quality Control process ④.

3-1-2 Quality control

Using the interactive scroll bars, users can easily exclude cells with gene counts above 2,500 ① or below 200 ②, and those with mitochondrial content exceeding 5% ③, in accordance with the Seurat - Guided Clustering Tutorial.

ShinySC provides histograms and violin plots for count depth, gene numbers, and mitochondrial gene fractions per cell, essential for quality control and identifying low-quality cells in single-cell RNA sequencing.

3.1.3 Feature selection

After removing unwanted cells, the next step is data normalization. ShinySC offers the LogNormalize method by default, which scales and log-transforms feature expressions. Alternatively, users can also select the SCTransform method via a convenient drop-down menu.

ShinySC selects the 2,000 most variably expressed genes by default for downstream PCA analysis, highlighting key biological signals and enhancing the efficiency and insightfulness of subsequent analyses.

All the processes mentioned above will be automatically performed after clicking the "STEP 3 (Feature Selection)" button.

3-1-4 Clustering

After selecting the optimal resolution from the Clustree plot, proceed to STEP4 (Clustering) ④ to initiate cell clustering. Utilizing both tSNE ⑤ and UMAP ⑥ methods preserves local distances, enhancing the understanding of cellular composition and heterogeneity. This approach ensures consistent clustering results with the Seurat tutorial. Interactive features ⑦ for toggling labels and adjusting label size, plot width, and height facilitate the creation of publication-ready figures.

3-1-5 Automatic cell-type annotation ＆ Find Gene Markers

First, select the ScType algorithm ①. Then, choose the appropriate tissue type ② for peripheral blood mononuclear cells (PBMCs). Finally, click “Annotate with ScType" button ③ to annotate the cell clusters ④.

Select scCATCH via the radio button ①, then choose Blood-associated tissue types through the cascade filters ②, including blood, peripheral blood, plasma, serum, umbilical cord blood, and venous blood. The corresponding markers will be displayed in an interactive table for annotating cell clusters ③.

Users can choose between scCATCH's algorithm (Slow) ④ and Seurat's Find,AllMarkers (Fast) for identifying highly expressed gene markers and matching these potential markers with known tissue-specific cell markers ③⑥.

To annotate a PBMC dataset using ShinySC, select SingleR through the radio button ①, then choose "(Human) NovershternHematopoieticData" as the reference dataset ②, which contains hematopoietic lineage data for PBMC annotation. Click the "Run" button ③ to start the process, and the UMAP plot will display the annotated cell types. Using SingleR, PBMC subsets such as Basophils, B cells, CD4+ T cells, CD8+ T cells, NK cells, Monocytes, Dendritic cells, Granulocytes, and HSCs (Hematopoietic Stem Cells) are identified ④.

Unlike ScType and scCATCH, which feature built-in gene marker identification and scoring algorithms, GPTCelltype lacks these capabilities and instead depends on Seurat's FindAllMarkers function. ShinySC addresses this limitation by seamlessly integrating FindAllMarkers with GPTCelltype, allowing users to initiate the process with a simple click of the Run button ①.

ShinySC includes a switch button ② for users to identify differentially expressed gene markers as positive only or both positive and negative using Seurat's FindAllMarkers function ③.

Resulting gene markers ④ can be further filtered by adjusted p-value, average log fold change, and pct.diff, where pct.diff represents the difference in gene expression percentage between the cluster and all other cells ⑤.

A dot plot is utilized to confirm the expression patterns of marker genes, whereas UMAP is employed to assess the specificity of these gene markers across cell clusters ⑥.

Once gene markers for individual clusters are identified, users can click the Annotate with GPT-4o button ⑦ to perform automatic cell type annotation using GPTCelltype.

After entering the OpenAI API key ⑧, GPTCelltype automatically annotates cell types ⑨ using marker gene information from the preceding gene marker analysis workflow ⑩.

• To register for an OpenAI API key, follow these steps:

  1. Sign Up or Log In:
     • Visit the OpenAI website.
     • Click on "Sign Up" to create a new account or "Log In" if you already have an account.

  2. Navigate to API Section:
     • After logging in, go to the API section. This is usually found in the dashboard or in the account settings menu.

  3. Create a New API Key:
     • Look for an option to create a new API key. This might be labeled as "New API Key," "Generate API Key," or similar.
     • Click on this option and follow the prompts to generate a new key.

  4. Copy and Secure Your API Key:
     • Once generated, copy the API key and store it securely. Do not share this key publicly or with unauthorized individuals.

  5. Add Billing Information:
     • Ensure that your account has the necessary billing information set up. The API usage might require a credit card or other payment method to be linked to your account.

  6. Use Your API Key:
     • Use this API key in your applications, such as ShinySC, to access GPT-4o capabilities.

  For detailed instructions, you can refer to OpenAI's official documentation or support resources.

3-1-6 Summary of Cell-Type Annotation

Automated cell labeling methods offer convenience and organization but heavily depend on recognized marker genes for each cell type. These methods efficiently categorize primary cell types like B cells, Natural Killer cells, Dendritic cells, and Platelets. However, distinguishing subtypes such as Regulatory T cells, Helper T cells, Cytotoxic T cells, and Memory T cells can be challenging. Conflicting labels within a cluster indicate the presence of different cell subtypes. To resolve these conflicts, a majority-rule approach prioritizing consensus labels or using more general labels can be employed. When uncertainty arises, experts should adjust initial clustering parameters and utilize additional features to improve cluster labels.

The "Custom_Label" functionality allows users to modify cell-type annotations, as demonstrated in the figure above. These labels are aligned with annotations from the Seurat tutorial, ensuring consistency and facilitating direct comparisons across different annotation algorithms.

3-2 Example 2 - Batch correction and condition-specific Analysis

To demonstrate functionality, users may enable the "Use Demo Datasets" option ① ② to load PBMC data from control and interferon-β–stimulated conditions. Integration is performed ③ via Seurat’s CCA-based FindIntegrationAnchors() and IntegrateData() functions within the Batch Correction module.

UMAP plots before ① and after ② integration enable visual assessment of cell population alignment .

To enable visual assessment of cell population alignment, users can activate the “Split by orig.ident” option ⑤ in the plot settings panel ③. This separates the UMAP visualization by sample condition— IMMUNE_CTRL and IMMUNE_STIM—allowing direct comparison of cell distributions. Ensure that the “Group by” field ④ is set to seurat_annotations to display cell-type identities. Enabling “Show Labels” further assists in verifying alignment of shared cell types across conditions.

The integrated Seurat object is downloadable in .rds format for downstream differential expression analysis.

The integrated Seurat object was uploaded via the “Data Upload” module ① by selecting Seurat R object (.rds) ② as the input format and Homo sapiens as the organism. Since the dataset had been preprocessed, the Quality Control step was skipped ③, allowing the analysis to proceed directly to feature selection ④.

As informed by the clustree visualization, a resolution of 0.3 stably reproduced 14 distinct clusters, aligning with the results from the official Seurat tutorial.

The analysis followed the same workflow outlined in Example 1 and concluded with cell-type annotation.

In ShinySC, condition-specific differential expression analysis is performed through the Differential Expression module ①. Users begin by loading the integrated Seurat object ②, then specify the relevant columns for cell type annotations (e.g., seurat_annotations, ③) and experimental conditions (e.g., stim, ④) via dropdown menus. The target cell type or cluster for comparison (e.g., CD14 Mono) is selected, followed by execution of the analysis using the Run DEG Analysis button ⑤.

Differentially expressed genes were identified using Seurat’s FindMarkers() function and presented in an interactive, searchable table. Users can search for a gene of interest (e.g., CD3D) using the search box ①. By clicking on a specific gene entry ②, corresponding expression patterns can be visualized instantly through UMAP, dot plot, or violin plot views. This integration enables rapid and intuitive comparison of gene expression across cell types or conditions.

The results aligned with Kang et al., showing stable expression of canonical markers (e.g., CD3D, GNLY) across conditions, while interferon-stimulated genes (IFI6, ISG15) were broadly upregulated. CD14 decreased in monocytes, and CXCL10 increased in monocytes and B cells, highlighting the value of integrated analysis in revealing both shared and cell-type–specific responses to interferon.