PBMC single-cell CITE-seq and TCR repertoire analysis

This repository contains an R workflow for analyzing peripheral blood mononuclear cell (PBMC) CITE-seq and T-cell receptor sequencing (TCR-seq) data in alcoholic hepatitis cohorts. The workflow covers Seurat object creation, DSB normalization of antibody-derived tags, Harmony/Seurat integration, multimodal UMAP visualization, Azimuth PBMC annotation, CD4 T-cell differential expression, scRepertoire-based clonotype analysis, and McPAS-TCR antigen-specificity annotation.

The repository is designed for public GitHub review. Raw 10x files, Seurat objects, local .RData files, and private clinical metadata are not included.

Study design

The analysis is based on PBMCs from four groups:

Group	Description
HC	Healthy controls
HD	Heavy drinkers without significant liver disease
AH	Alcoholic hepatitis patients without infection within the study window
AH-I / AHI	Alcoholic hepatitis patients who developed infection within 30 days of blood draw

The project uses CITE-seq, single-cell RNA-seq, and 10x TCR-seq to compare PBMC cell states, T-cell populations, clonotype expansion, and antigen-specific TCR patterns.

Repository structure

pbmc-single-cell-tcr-analysis/
├── README.md
├── CITATION.cff
├── LICENSE
├── .gitignore
├── config/
│   ├── sample_manifest_template.csv
│   ├── tcr_manifest_template.csv
│   └── pathway_gene_sets.csv
├── data/
│   ├── README.md
│   ├── raw/
│   ├── processed/
│   └── reference/
├── docs/
│   ├── public_release_checklist.md
│   └── workflow_notes.md
├── figures/
│   ├── README.md
│   ├── figure_index.csv
│   └── extracted/
├── notebooks/
│   └── pbmc_single_cell_tcr_workflow.Rmd
├── results/
│   ├── README.md
│   ├── tables/
│   └── objects/
└── scripts/
    ├── 00_install_dependencies.R
    ├── 01_create_seurat_objects.R
    ├── 02_integrate_cluster_annotate.R
    ├── 03_cell_type_counts_and_umaps.R
    ├── 04_cd4_differential_expression.R
    ├── 05_tcr_repertoire_analysis.R
    ├── 06_mcpas_tcr_annotation.R
    ├── run_workflow.R
    └── utils.R

Main workflow

Install packages once:

source("scripts/00_install_dependencies.R")

Then run the steps in order from the repository root:

source("scripts/01_create_seurat_objects.R")
source("scripts/02_integrate_cluster_annotate.R")
source("scripts/03_cell_type_counts_and_umaps.R")
source("scripts/04_cd4_differential_expression.R")
source("scripts/05_tcr_repertoire_analysis.R")
source("scripts/06_mcpas_tcr_annotation.R")

For command-line use, the scripts also accept simple flags. Example:

Rscript scripts/01_create_seurat_objects.R --manifest config/sample_manifest_template.csv --out results/objects/seurat_objects.rds

Required input files

The public repository uses placeholder paths. Before running locally, edit the manifest files:

config/sample_manifest_template.csv
config/tcr_manifest_template.csv

Use paths like this in the public version:

/path/to/AH1_142/raw_feature_bc_matrix
/path/to/AH1_142/sample_filtered_feature_bc_matrix
/path/to/AH1_142/outs/filtered_contig_annotations.csv

Do not commit private absolute paths such as lab server paths or personal computer paths.

Public figures and result tables

Public figure exports from the supplied slide deck are stored in:

figures/extracted/

Summary result tables are stored in:

results/tables/

Selected examples:

Output	Description
figure_03_harmony_umap_clusters.png	Integrated UMAP clusters
figure_04_azimuth_cell_type_annotation.png	Azimuth PBMC cell-type annotation
figure_09_cd4_t_cell_deg_heatmap.png	CD4 T-cell pathway heatmap
figure_10_tcr_unique_clonotypes.png	TCR unique clonotype quantification
figure_15A_mcpas_alluvial_ahi.png	AHI McPAS-TCR antigen-status alluvial plot
figure_15B_mcpas_alluvial_ah.png	AH McPAS-TCR antigen-status alluvial plot

Data privacy

This repository should not contain raw sequencing data or protected clinical metadata. Keep these file types private unless you have approval and a data-sharing plan:

*.fastq.gz
*.bam
*.h5
*.h5ad
*.rds
*.RData
filtered_feature_bc_matrix/
raw_feature_bc_matrix/
filtered_contig_annotations.csv

The included CSV tables are figure-level summaries, not raw single-cell matrices.

Figure rights note

Some figures may include third-party or BioRender/10x Genomics-derived content. Confirm that each figure is allowed to be shared publicly before publishing the repository.

Suggested repository name

pbmc-single-cell-tcr-analysis

Suggested GitHub topics:

single-cell, scrna-seq, cite-seq, tcr-seq, pbmc, seurat, azimuth, screpertoire, immunology, bioinformatics, r