Single Cell Expression Analysis Pipeline

A comprehensive pipeline for downloading, processing, and visualizing single-cell RNA sequencing data from GEO datasets. This pipeline creates UMAP expression plots for genes of interest with customizable parameters.

Overview

This pipeline performs the following steps:

1. Downloads single-cell datasets from NCBI GEO
2. Processes the data using Seurat (normalization, integration, clustering)
3. Generates publication-ready UMAP expression plots for specified genes

Features

• ✅ Automated data download from GEO with smart caching
• ✅ Configurable analysis parameters via YAML config files
• ✅ Batch integration using Harmony
• ✅ Quality control and filtering
• ✅ Customizable plotting (colors, sizes, layouts)
• ✅ Error handling and progress reporting
• ✅ Flexible gene selection with validation

Requirements

System Requirements

• R (≥ 4.0.0)
• Bash shell
• wget for downloading files
• tar for extracting archives

R Packages

The script will automatically check for and prompt you to install missing packages:

install.packages(c("Seurat", "ggplot2", "yaml", "cowplot", "dplyr"))

Quick Start

1. Clone/Download the Pipeline

# Download the scripts to your working directory
# Ensure you have: get_files.sh, index/make_expression_figures.R

2. Make Scripts Executable

chmod +x get_files.sh

3. Run the Complete Pipeline

# Download data and run analysis with default settings
./get_files.sh

4. Or Skip Download (if you already have the data)

# Skip download and just run the analysis
./get_files.sh --skip-download

Configuration

Config File Structure

The pipeline uses a YAML configuration file (config.yaml)

# Genes to analyze
genes:
  - "Col4a1"
  - "Col4a2"
  - "Pdgfra"
  - "Olig2"

# Color scheme for expression plots
colors:
  low: "grey90"      # Low expression color
  high: "blue"       # High expression color
  na_color: "lightgrey"

# Plot appearance
plot_settings:
  point_size: 0.1           # Size of points in UMAP
  width_per_plot: 4         # Width per individual plot
  height_per_plot: 4        # Height per individual plot
  title_size: 12            # Title font size
  dpi: 300                  # Output resolution

# Analysis parameters
seurat_params:
  min_cells: 3              # Min cells expressing a gene
  min_features: 200         # Min features per cell
  min_nFeature_RNA: 750     # Min RNA features for filtering
  max_nFeature_RNA: 5500    # Max RNA features for filtering
  max_percent_mt: 25        # Max mitochondrial percentage
  pca_dims: 20              # PCA dimensions to use
  resolution: 0.5           # Clustering resolution

# Output settings
output:
  filename_prefix: "expression_figures"
  format: "png"             # png, pdf, svg, etc.
  save_seurat_object: TRUE # Save processed Seurat object
  seurat_filename: "processed_seurat_object.rds"

Customizing Your Analysis

1. Change Genes to Plot

Edit config.yaml:

genes:
  - "Pdgfra"
  - "Olig2"
  - "Sox10"
  - "Mbp"

2. Try Different Color Schemes

colors:
  low: "lightblue"
  high: "darkred"

Popular color combinations:

• grey90 → blue (default, clean)
• lightblue → darkred (high contrast)
• white → purple (elegant)
• #F0F0F0 → #8B0000 (custom hex colors)

3. Adjust Plot Quality

plot_settings:
  point_size: 0.05    # Smaller points for high-density plots
  dpi: 600           # Higher resolution for publications
  width_per_plot: 5   # Larger individual plots

Usage Examples

Basic Usage

# Complete pipeline with default settings
./get_files.sh

# Skip download if data already exists
./get_files.sh --skip-download

# Get help
./get_files.sh --help

Advanced Usage

# Use custom config file
Rscript index/make_expression_figures.R my_custom_config.yaml

# Run only the R analysis (after manual data preparation)
Rscript index/make_expression_figures.R

Data Sources

This pipeline downloads the following datasets from GEO:

• GSM5973615: EAE1_total (seq batch #1)
• GSM5973616: EAE2_total (seq batch #1)
• GSM5973617: CTL1_total (seq batch #1)
• GSM5973620: EAE3_total (seq batch #2)
• GSM5973621: CTL2_total (seq batch #2)
• GSM5973622: CTL3_total (seq batch #2)

The data represents single-cell RNA-seq from control (CTL) and experimental autoimmune encephalomyelitis (EAE) samples.

Output Files

Generated Files

• Expression plots: expression_figures_[genes].png
• Config file: config.yaml (auto-generated if missing)
• Seurat object: processed_seurat_object.rds (optional)
• Downloaded data: *_total.tar.gz and extracted directories

Plot Layout

• 1 gene: Single plot
• 2 genes: Side-by-side (2×1)
• 3-4 genes: 2×2 grid
• 5-6 genes: 3×2 grid
• 7-9 genes: 3×3 grid
• 10+ genes: 4×n grid

Troubleshooting

Common Issues

1. Missing R Packages

Error: Missing required packages: Seurat, ggplot2

Solution: Install missing packages:

install.packages(c("Seurat", "ggplot2", "yaml", "cowplot", "dplyr"))

2. Gene Not Found

Warning: Gene Pdgfra not found in dataset
Similar genes: Pdgfrb, Pdgfrl, Pdgfc

Solution: Check gene spelling or try suggested alternatives

3. Download Failures

Error: No valid input directories found!

Solution:

• Check internet connection
• Verify GEO dataset availability
• Try running without --skip-download

4. Memory Issues

For large datasets, you might encounter memory issues: Solution:

• Increase system RAM
• Reduce max_nFeature_RNA in config
• Process fewer samples at once

Getting Help

1. Check the config file: Ensure config.yaml has correct parameters
2. Verify data: Make sure extracted directories exist
3. Check R packages: Ensure all required packages are installed
4. Review error messages: The script provides detailed error information

File Structure

your_project/
├── get_files.sh                    # Main pipeline script
├── make_expression_figures.R   # R analysis script
├── config.yaml                     # Configuration file (auto-generated)
├── *_total.tar.gz                  # Downloaded data archives
├── *_total/                        # Extracted data directories
└── expression_figures_*.png        # Output plots

Performance Notes

• Runtime: Typically 5-15 minutes depending on data size and parameters
• Memory: Requires ~4-8GB RAM for typical datasets
• Storage: ~2-5GB for downloaded and processed data

Citation

If you use this pipeline in your research, please cite the appropriate tools:

• Seurat: Hao et al. (2021) Integrated analysis of multimodal single-cell data. Cell
• Harmony: Korsunsky et al. (2019) Fast, sensitive and accurate integration of single-cell data with Harmony. Nature Methods

License

This pipeline is provided as-is for research purposes. Please respect the terms of use for the underlying tools and datasets.

---

Questions or Issues?

• Check the troubleshooting section above
• Verify your config file settings
• Ensure all dependencies are installed