# Introduction to ImmuneSigR

Welcome to `ImmuneSigR`. This package provides a rigorous, literature-derived database of immune cell markers formatted as Gene Matrix Transposed (GMT) files, alongside dependency-free rank-based and mean-expression scoring methods for single-cell RNA sequencing (scRNA-seq) data.

## 1. Database Exploration & Search

To ensure rigorous academic provenance, cell subpopulations in `ImmuneSigR` are distinguished by appending their source PubMed IDs (PMIDs) to their names (e.g., `Plasma cell_PMID_33208946`).

You can easily query the detailed metadata and search for specific cell lineages:

    library(ImmuneSigR)

    # Search for B cell related records
    b_cell_records <- Search_ImmuneSigR("B cell", search_by = "Cell_Type", fixed = TRUE)
    #> Found 110 matching cell signatures.
    head(b_cell_records[, c("cell_name", "Title", "PMID")])
    #>                               cell_name
    #> 1                  B cell_PMID_33208946
    #> 2             Plasma cell_PMID_33208946
    #> 24                 B cell_PMID_33208946
    #> 25                 Plasma_PMID_33208946
    #> 43 Resting Memory B cells_PMID_39406187
    #> 44      Activated B cells_PMID_39406187
    #>                                                                       Title
    #> 1  A molecular cell atlas of the human lung from single cell RNA sequencing
    #> 2  A molecular cell atlas of the human lung from single cell RNA sequencing
    #> 24 A molecular cell atlas of the human lung from single cell RNA sequencing
    #> 25 A molecular cell atlas of the human lung from single cell RNA sequencing
    #> 43           A pan-cancer single-cell RNA-seq atlas of intratumoral B cells
    #> 44           A pan-cancer single-cell RNA-seq atlas of intratumoral B cells
    #>        PMID
    #> 1  33208946
    #> 2  33208946
    #> 24 33208946
    #> 25 33208946
    #> 43 39406187
    #> 44 39406187

    # Retrieve marker genes (filtering for signatures with at least 5 genes)
    t_nk_markers <- Get_Markers(c("T cell", "NK cell"), min_genes = 5)
    length(t_nk_markers)
    #> [1] 192

## 2. Base R Scoring (Dependency-Free)

`ImmuneSigR` provides robust scoring functions that do not require heavy external dependencies. We can validate this using a simulated matrix:

    # Create a dummy expression matrix for demonstration
    demo_genes <- unique(unlist(Get_Markers(c("B cell", "T cell"), min_genes = 5)[1:8]))
    demo_genes <- demo_genes[seq_len(min(120, length(demo_genes)))]

    set.seed(1)
    expr_matrix_dummy <- matrix(
      stats::rpois(length(demo_genes) * 12, lambda = 2),
      nrow = length(demo_genes),
      dimnames = list(demo_genes, paste0("cell_", seq_len(12)))
    )

    # Calculate Rank Scores (UCell-like)
    matrix_rank_scores <- Score_ImmuneSigR(
      expr_matrix_dummy,
      target_cells = c("B cell", "T cell"),
      min_genes = 5,
      method = "rank"
    )
    #> Scoring 65 signatures using rank scoring...
    head(matrix_rank_scores)
    #>        ImmuneSigR_B cell_PMID_33208946_score
    #> cell_1                                     1
    #> cell_2                                     1
    #> cell_3                                     1
    #> cell_4                                     1
    #> cell_5                                     1
    #> cell_6                                     1
    #>        ImmuneSigR_B cell_PMID_33208946.1_score
    #> cell_1                               0.6134752
    #> cell_2                               0.6050271
    #> cell_3                               0.6125365
    #> cell_4                               0.5833333
    #> cell_5                               0.6136838
    #> cell_6                               0.6740718
    #>        ImmuneSigR_Activated B cells_PMID_39406187_score
    #> cell_1                                        0.5803844
    #> cell_2                                        0.5024028
    #> cell_3                                        0.5454347
    #> cell_4                                        0.5729576
    #> cell_5                                        0.4130625
    #> cell_6                                        0.5255570
    #>        ImmuneSigR_Naive B cells_PMID_39406187_score
    #> cell_1                                    0.6231884
    #> cell_2                                    0.5623188
    #> cell_3                                    0.6434783
    #> cell_4                                    0.4149758
    #> cell_5                                    0.4444444
    #> cell_6                                    0.6212560
    #>        ImmuneSigR_Atypical Memory B cells_PMID_39406187_score
    #> cell_1                                              0.6206897
    #> cell_2                                              0.5966749
    #> cell_3                                              0.5135468
    #> cell_4                                              0.5548030
    #> cell_5                                              0.3325123
    #> cell_6                                              0.3054187
    #>        ImmuneSigR_B cells/MHC-II_PMID_37316583_score
    #> cell_1                                     0.6698630
    #> cell_2                                     0.4956621
    #> cell_3                                     0.5091324
    #> cell_4                                     0.6392694
    #> cell_5                                     0.5118721
    #> cell_6                                     0.5744292
    #>        ImmuneSigR_B cells/Stress_PMID_37316583_score
    #> cell_1                                     0.5087440
    #> cell_2                                     0.4875464
    #> cell_3                                     0.6809751
    #> cell_4                                     0.5630631
    #> cell_5                                     0.5437202
    #> cell_6                                     0.6043985
    #>        ImmuneSigR_B cells/Germinal Center_PMID_37316583_score
    #> cell_1                                              0.4895320
    #> cell_2                                              0.3903941
    #> cell_3                                              0.4913793
    #> cell_4                                              0.3793103
    #> cell_5                                              0.6139163
    #> cell_6                                              0.4094828
    #>        ImmuneSigR_B cells/Progenitor_PMID_37316583_score
    #> cell_1                                         0.4520744
    #> cell_2                                         0.3948498
    #> cell_3                                         0.6881259
    #> cell_4                                         0.5729614
    #> cell_5                                         0.4849785
    #> cell_6                                         0.4012876
    #>        ImmuneSigR_B cells/B-cells1_PMID_37316583_score
    #> cell_1                                       0.4034335
    #> cell_2                                       0.4542203
    #> cell_3                                       0.6652361
    #> cell_4                                       0.5572246
    #> cell_5                                       0.4842632
    #> cell_6                                       0.4420601
    #>        ImmuneSigR_B cell Clusters _Cluster1_PMID_31924475_score
    #> cell_1                                                0.4930100
    #> cell_2                                                0.5812582
    #> cell_3                                                0.5043687
    #> cell_4                                                0.5299257
    #> cell_5                                                0.6301879
    #> cell_6                                                0.5052425
    #>        ImmuneSigR_B cell Clusters _Cluster2_PMID_31924475_score
    #> cell_1                                                0.5643067
    #> cell_2                                                0.5573942
    #> cell_3                                                0.5303729
    #> cell_4                                                0.5113113
    #> cell_5                                                0.6143695
    #> cell_6                                                0.5261835
    #>        ImmuneSigR_B cell Clusters _Cluster3_PMID_31924475_score
    #> cell_1                                                0.4324786
    #> cell_2                                                0.4991453
    #> cell_3                                                0.6777778
    #> cell_4                                                0.6316239
    #> cell_5                                                0.6811966
    #> cell_6                                                0.1641026
    #>        ImmuneSigR_B cell Clusters _Cluster4_PMID_31924475_score
    #> cell_1                                                0.2854701
    #> cell_2                                                0.4991453
    #> cell_3                                                0.6094017
    #> cell_4                                                0.6760684
    #> cell_5                                                0.5384615
    #> cell_6                                                0.2213675
    #>        ImmuneSigR_B cell Clusters _Cluster6_PMID_31924475_score
    #> cell_1                                                0.4136752
    #> cell_2                                                0.4820513
    #> cell_3                                                0.6470085
    #> cell_4                                                0.4760684
    #> cell_5                                                0.5384615
    #> cell_6                                                0.6367521
    #>        ImmuneSigR_B cell Clusters _Cluster7_PMID_31924475_score
    #> cell_1                                                0.5213675
    #> cell_2                                                0.6581197
    #> cell_3                                                0.4538462
    #> cell_4                                                0.1974359
    #> cell_5                                                0.4316239
    #> cell_6                                                0.2333333
    #>        ImmuneSigR_B cells_PMID_31033233_score
    #> cell_1                              0.4980064
    #> cell_2                              0.5163477
    #> cell_3                              0.5267145
    #> cell_4                              0.7013557
    #> cell_5                              0.4904306
    #> cell_6                              0.4649123
    #>        ImmuneSigR_B cell_PMID_33711272_score
    #> cell_1                             0.6387435
    #> cell_2                             0.6167103
    #> cell_3                             0.6037304
    #> cell_4                             0.5976222
    #> cell_5                             0.5811518
    #> cell_6                             0.5890052
    #>        ImmuneSigR_B cell_PMID_33861994_score
    #> cell_1                             0.7004227
    #> cell_2                             0.6732037
    #> cell_3                             0.6921386
    #> cell_4                             0.6791209
    #> cell_5                             0.6595097
    #> cell_6                             0.7027895
    #>        ImmuneSigR_B cell_PMID_34019793_score
    #> cell_1                             0.4435897
    #> cell_2                             0.7641026
    #> cell_3                             0.5059829
    #> cell_4                             0.3350427
    #> cell_5                             0.6273504
    #> cell_6                             0.5905983
    #>        ImmuneSigR_B Cells_PMID_31980621_score
    #> cell_1                              0.6466165
    #> cell_2                              0.6387755
    #> cell_3                              0.6484425
    #> cell_4                              0.6526316
    #> cell_5                              0.6336198
    #> cell_6                              0.5909774
    #>        ImmuneSigR_B cells_B0_TNFRSF13B_PMID_37427448_score
    #> cell_1                                           0.6543670
    #> cell_2                                           0.5568720
    #> cell_3                                           0.5201422
    #> cell_4                                           0.6113744
    #> cell_5                                           0.5419770
    #> cell_6                                           0.5267434
    #>        ImmuneSigR_B cells_B1_S1PR1_PMID_37427448_score
    #> cell_1                                       0.6492554
    #> cell_2                                       0.5840779
    #> cell_3                                       0.6541810
    #> cell_4                                       0.6154639
    #> cell_5                                       0.5726231
    #> cell_6                                       0.5896907
    #>        ImmuneSigR_B cells_B3_NEIL1_PMID_37427448_score
    #> cell_1                                       0.5932710
    #> cell_2                                       0.4515888
    #> cell_3                                       0.5052336
    #> cell_4                                       0.5325234
    #> cell_5                                       0.6076636
    #> cell_6                                       0.5085981
    #>        ImmuneSigR_B cells Naive_PMID_34493872_score
    #> cell_1                                    0.4685772
    #> cell_2                                    0.6319759
    #> cell_3                                    0.6025641
    #> cell_4                                    0.5867270
    #> cell_5                                    0.5397185
    #> cell_6                                    0.6671694
    #>        ImmuneSigR_B cell/BC_GPR183_PMID_34238352_score
    #> cell_1                                       0.6568627
    #> cell_2                                       0.5951245
    #> cell_3                                       0.5180180
    #> cell_4                                       0.6070482
    #> cell_5                                       0.5368309
    #> cell_6                                       0.4798622
    #>        ImmuneSigR_MBM_sc_bcells_Activated B cells_PMID_35803246_score
    #> cell_1                                                      0.7018508
    #> cell_2                                                      0.6487372
    #> cell_3                                                      0.5921535
    #> cell_4                                                      0.6529786
    #> cell_5                                                      0.6737035
    #> cell_6                                                      0.6707152
    #>        ImmuneSigR_MBM_sc_bcells_Na鈭毭榲e B cells_PMID_35803246_score
    #> cell_1                                                      0.5806410
    #> cell_2                                                      0.5405128
    #> cell_3                                                      0.6367949
    #> cell_4                                                      0.6016667
    #> cell_5                                                      0.6566667
    #> cell_6                                                      0.6582051
    #>        ImmuneSigR_B CELL_PMID_30388455_score
    #> cell_1                             0.5487923
    #> cell_2                             0.4826087
    #> cell_3                             0.4603865
    #> cell_4                             0.3502415
    #> cell_5                             0.5425121
    #> cell_6                             0.6367150
    #>        ImmuneSigR_G1- B cells_PMID_30388456_score
    #> cell_1                                  0.6789921
    #> cell_2                                  0.6537958
    #> cell_3                                  0.5580279
    #> cell_4                                  0.6511780
    #> cell_5                                  0.6460515
    #> cell_6                                  0.6151832
    #>        ImmuneSigR_B cells_PMID_24138885_score
    #> cell_1                              0.4980064
    #> cell_2                              0.5163477
    #> cell_3                              0.5267145
    #> cell_4                              0.7013557
    #> cell_5                              0.4904306
    #> cell_6                              0.4649123
    #>        ImmuneSigR_Human_Eosinophil_B cells_PMID_38871184_score
    #> cell_1                                               0.5930841
    #> cell_2                                               0.5854206
    #> cell_3                                               0.4685981
    #> cell_4                                               0.5194393
    #> cell_5                                               0.6345794
    #> cell_6                                               0.4992523
    #>        ImmuneSigR_T cell/Exhaustion signature_PMID_38855191_score
    #> cell_1                                                  0.6666667
    #> cell_2                                                  0.6201717
    #> cell_3                                                  0.5672389
    #> cell_4                                                  0.5965665
    #> cell_5                                                  0.5593705
    #> cell_6                                                  0.4134478
    #>        ImmuneSigR_CD4 T cells/Naive1_PMID_37316583_score
    #> cell_1                                         0.5836910
    #> cell_2                                         0.4062947
    #> cell_3                                         0.5965665
    #> cell_4                                         0.5500715
    #> cell_5                                         0.4971388
    #> cell_6                                         0.6022890
    #>        ImmuneSigR_CD4 T cells/Naive2_PMID_37316583_score
    #> cell_1                                         0.6030568
    #> cell_2                                         0.4851528
    #> cell_3                                         0.6318777
    #> cell_4                                         0.5602620
    #> cell_5                                         0.4912664
    #> cell_6                                         0.5109170
    #>        ImmuneSigR_CD8 T cells/Memory/Naive1_PMID_37316583_score
    #> cell_1                                                0.5178571
    #> cell_2                                                0.4285714
    #> cell_3                                                0.5985222
    #> cell_4                                                0.4322660
    #> cell_5                                                0.5104680
    #> cell_6                                                0.5831281
    #>        ImmuneSigR_CD8 T cells/Unassigned1_PMID_37316583_score
    #> cell_1                                              0.5213675
    #> cell_2                                              0.4111111
    #> cell_3                                              0.3230769
    #> cell_4                                              0.6324786
    #> cell_5                                              0.6017094
    #> cell_6                                              0.5905983
    #>        ImmuneSigR_CD8 T cells/Naive2_PMID_37316583_score
    #> cell_1                                         0.6380323
    #> cell_2                                         0.4585169
    #> cell_3                                         0.5051395
    #> cell_4                                         0.5040382
    #> cell_5                                         0.6101322
    #> cell_6                                         0.6361968
    #>        ImmuneSigR_CD8 T cells/Dysfunction_PMID_37316583_score
    #> cell_1                                              0.7008547
    #> cell_2                                              0.4991453
    #> cell_3                                              0.6025641
    #> cell_4                                              0.3794872
    #> cell_5                                              0.5264957
    #> cell_6                                              0.6059829
    #>        ImmuneSigR_CD8+ T cells/cell state 1_PMID_32385277_score
    #> cell_1                                                0.5026201
    #> cell_2                                                0.6026201
    #> cell_3                                                0.4537118
    #> cell_4                                                0.5742358
    #> cell_5                                                0.6039301
    #> cell_6                                                0.4829694
    #>        ImmuneSigR_CD8+ T cells/cell state 2_PMID_32385277_score
    #> cell_1                                                0.4919558
    #> cell_2                                                0.6098542
    #> cell_3                                                0.5658622
    #> cell_4                                                0.5482655
    #> cell_5                                                0.6616390
    #> cell_6                                                0.5997989
    #>        ImmuneSigR_CD8+ T cells/cell state 3_PMID_32385277_score
    #> cell_1                                                0.6015737
    #> cell_2                                                0.4656652
    #> cell_3                                                0.5793991
    #> cell_4                                                0.5157368
    #> cell_5                                                0.6165951
    #> cell_6                                                0.5350501
    #>        ImmuneSigR_T cell/1_PMID_32822576_score
    #> cell_1                               0.4671498
    #> cell_2                               0.6492754
    #> cell_3                               0.5888889
    #> cell_4                               0.5927536
    #> cell_5                               0.5405797
    #> cell_6                               0.2980676
    #>        ImmuneSigR_T cell/2_PMID_32822576_score
    #> cell_1                               0.5972887
    #> cell_2                               0.4222488
    #> cell_3                               0.5199362
    #> cell_4                               0.4685008
    #> cell_5                               0.3644338
    #> cell_6                               0.4673046
    #>        ImmuneSigR_T cell/CD4-C3-CD27_PMID_31588021_score
    #> cell_1                                         0.4162393
    #> cell_2                                         0.4376068
    #> cell_3                                         0.5512821
    #> cell_4                                         0.4905983
    #> cell_5                                         0.5803419
    #> cell_6                                         0.3777778
    #>        ImmuneSigR_T cell/CD4-C4-CTLA4_PMID_31588021_score
    #> cell_1                                          0.6423767
    #> cell_2                                          0.5339126
    #> cell_3                                          0.4971973
    #> cell_4                                          0.6647982
    #> cell_5                                          0.5355942
    #> cell_6                                          0.3946188
    #>        ImmuneSigR_T cell/CD4-C6-CCR7_PMID_31588021_score
    #> cell_1                                         0.4454106
    #> cell_2                                         0.5724638
    #> cell_3                                         0.7033816
    #> cell_4                                         0.4777778
    #> cell_5                                         0.6183575
    #> cell_6                                         0.4685990
    #>        ImmuneSigR_T cell/CD4-C4-CTLA4_PMID_31588021.1_score
    #> cell_1                                            0.7803419
    #> cell_2                                            0.5341880
    #> cell_3                                            0.4333333
    #> cell_4                                            0.4760684
    #> cell_5                                            0.4341880
    #> cell_6                                            0.6059829
    #>        ImmuneSigR_41BB-Hi CD8+ T cell_PMID_33711272_score
    #> cell_1                                          0.6188198
    #> cell_2                                          0.6379585
    #> cell_3                                          0.6148325
    #> cell_4                                          0.6363636
    #> cell_5                                          0.4059011
    #> cell_6                                          0.3137959
    #>        ImmuneSigR_41BB-Hi CD8+ T cell_PMID_33711272.1_score
    #> cell_1                                            0.6227074
    #> cell_2                                            0.7056769
    #> cell_3                                            0.6096070
    #> cell_4                                            0.6270742
    #> cell_5                                            0.4650655
    #> cell_6                                            0.3973799
    #>        ImmuneSigR_41BB-Lo CD8+ T cell_PMID_33711272.1_score
    #> cell_1                                            0.6001431
    #> cell_2                                            0.4434907
    #> cell_3                                            0.2510730
    #> cell_4                                            0.6602289
    #> cell_5                                            0.4821173
    #> cell_6                                            0.5822604
    #>        ImmuneSigR_CD8, gamma delta t cells_PMID_31980621_score
    #> cell_1                                               0.5240148
    #> cell_2                                               0.5591133
    #> cell_3                                               0.4279557
    #> cell_4                                               0.5566502
    #> cell_5                                               0.5862069
    #> cell_6                                               0.6046798
    #>        ImmuneSigR_Naive T Cells_PMID_31980621_score
    #> cell_1                                    0.5448430
    #> cell_2                                    0.5257848
    #> cell_3                                    0.5014013
    #> cell_4                                    0.5403587
    #> cell_5                                    0.5599776
    #> cell_6                                    0.5860426
    #>        ImmuneSigR_T cells_CD4_CCR7_PMID_37427448_score
    #> cell_1                                       0.7229064
    #> cell_2                                       0.4796798
    #> cell_3                                       0.5061576
    #> cell_4                                       0.5116995
    #> cell_5                                       0.4963054
    #> cell_6                                       0.5775862
    #>        ImmuneSigR_T cells_Treg_FOXP3_PMID_37427448_score
    #> cell_1                                         0.6896552
    #> cell_2                                         0.3903941
    #> cell_3                                         0.6551724
    #> cell_4                                         0.5018473
    #> cell_5                                         0.5412562
    #> cell_6                                         0.4784483
    #>        ImmuneSigR_KUL3 T cells_Cluster0_PMID_32451460_score
    #> cell_1                                            0.6299517
    #> cell_2                                            0.4574879
    #> cell_3                                            0.5594203
    #> cell_4                                            0.4898551
    #> cell_5                                            0.5797101
    #> cell_6                                            0.5222222
    #>        ImmuneSigR_KUL3 T cells_Cluster1_PMID_32451460_score
    #> cell_1                                            0.4196581
    #> cell_2                                            0.4726496
    #> cell_3                                            0.3880342
    #> cell_4                                            0.7324786
    #> cell_5                                            0.3811966
    #> cell_6                                            0.4606838
    #>        ImmuneSigR_KUL3 T cells_Cluster2_PMID_32451460_score
    #> cell_1                                            0.4002723
    #> cell_2                                            0.5479918
    #> cell_3                                            0.7539142
    #> cell_4                                            0.5496937
    #> cell_5                                            0.5534377
    #> cell_6                                            0.4115044
    #>        ImmuneSigR_KUL3 T cells_Cluster3_PMID_32451460_score
    #> cell_1                                            0.5231884
    #> cell_2                                            0.6144928
    #> cell_3                                            0.6236715
    #> cell_4                                            0.6072464
    #> cell_5                                            0.5439614
    #> cell_6                                            0.5144928
    #>        ImmuneSigR_KUL3 T cells_Cluster10_PMID_32451460_score
    #> cell_1                                             0.5690821
    #> cell_2                                             0.5096618
    #> cell_3                                             0.6198068
    #> cell_4                                             0.4130435
    #> cell_5                                             0.3739130
    #> cell_6                                             0.4724638
    #>        ImmuneSigR_MBM_sc_tcells_CD8+ T cells TOX+_PMID_35803246_score
    #> cell_1                                                      0.6299261
    #> cell_2                                                      0.6693350
    #> cell_3                                                      0.5406404
    #> cell_4                                                      0.6151478
    #> cell_5                                                      0.4267241
    #> cell_6                                                      0.2967980
    #>        ImmuneSigR_MBM_sc_tcells_CD8+ T cells TCF7+_PMID_35803246_score
    #> cell_1                                                       0.5178571
    #> cell_2                                                       0.3811576
    #> cell_3                                                       0.3854680
    #> cell_4                                                       0.6065271
    #> cell_5                                                       0.5880542
    #> cell_6                                                       0.7173645
    #>        ImmuneSigR_MBM_sc_tcells_CD4+ T cells_PMID_35803246_score
    #> cell_1                                                 0.5752976
    #> cell_2                                                 0.4601190
    #> cell_3                                                 0.5482143
    #> cell_4                                                 0.5193452
    #> cell_5                                                 0.5627976
    #> cell_6                                                 0.6532738
    #>        ImmuneSigR_Human_Eosinophil_CD8 T cells_PMID_38871184_score
    #> cell_1                                                   0.5286797
    #> cell_2                                                   0.6412338
    #> cell_3                                                   0.4042208
    #> cell_4                                                   0.5800866
    #> cell_5                                                   0.4577922
    #> cell_6                                                   0.5303030
    #>        ImmuneSigR_Human_Eosinophil_CD4 T cells_PMID_38871184_score
    #> cell_1                                                   0.5960591
    #> cell_2                                                   0.4538177
    #> cell_3                                                   0.3799261
    #> cell_4                                                   0.6016010
    #> cell_5                                                   0.4605911
    #> cell_6                                                   0.6871921

## 3. Real Single-Cell Validation (Seurat Integration)

`ImmuneSigR` is designed to integrate seamlessly with real-world scRNA-seq workflows. Below is an example of applying targeted Plasma cell signatures to the PBMC 3k dataset.

(Note: The following code chunk is not evaluated during CRAN package building to avoid external data downloads, but you can run it locally in your R console).

    library(Seurat)
    library(SeuratData)
    library(ggplot2)

    # 1. Load and process pbmc3k dataset
    data("pbmc3k")
    pbmc <- UpdateSeuratObject(pbmc3k)
    pbmc <- NormalizeData(pbmc) |> FindVariableFeatures() |> ScaleData() |> RunPCA() |> RunUMAP(dims = 1:10)

    # 2. Extract expression matrix and define targets
    expr_matrix_real <- as.matrix(pbmc[["RNA"]]$data)
    real_targets <- c("Plasma cell_PMID_33208946", "Conventional Plasma cells_PMID_39406187")

    # 3. Score using precise targets curated from literature
    real_scores <- Score_ImmuneSigR(expr_matrix_real, target_cells = real_targets, min_genes = 5, method = "rank")

    # 4. Add to metadata and visualize
    pbmc <- AddMetaData(pbmc, metadata = real_scores)
    score_cols <- colnames(real_scores)

    p_umap <- FeaturePlot(pbmc, features = score_cols[1:2], ncol = 2, pt.size = 0.8) &
      scale_colour_gradientn(colours = rev(RColorBrewer::brewer.pal(n = 11, name = "RdYlBu")))

    # --- Plot Title Optimization (Publication Standard) ---
    # Restructure "ImmuneSigR_CellName_PMID_xxxx_score" to "CellName Signature Score\n(PMID: xxxx)"
    clean_titles <- gsub("^ImmuneSigR_(.+)_PMID_([0-9]+)_score$", "\\1 Signature Score\n(PMID: \\2)", score_cols[1:2])

    p_umap[[1]] <- p_umap[[1]] + ggtitle(clean_titles[1]) + theme(plot.title = element_text(hjust = 0.5, size = 12, face = "bold"))
    p_umap[[2]] <- p_umap[[2]] + ggtitle(clean_titles[2]) + theme(plot.title = element_text(hjust = 0.5, size = 12, face = "bold"))

    # Display the plot
    p_umap

## 4. GMT File Management

You can effortlessly export the built-in GMT database for external use (e.g., in GSEA) or create your own custom marker sets.

    # We use tempdir() here for CRAN compliance.
    # In practice, you can replace this with your desired output folder (e.g., getwd()).
    out_dir <- tempdir()

    # Export built-in GMT
    exported_gmt <- Export_ImmuneSigR_GMT(out_dir = out_dir)
    #> ImmuneSigR GMT file successfully exported to: C:\Users\梁颖妍\AppData\Local\Temp\RtmpM1v5zz/ImmuneSigR_signatures.gmt

    # Create a custom signature GMT
    custom_gmt <- Create_Custom_GMT(
      marker_list = list(
        Custom_T = c("CD3D", "CD3E", "CD8A"),
        Custom_B = c("CD19", "MS4A1", "CD79A")
      ),
      file_name = file.path(out_dir, "custom_demo_signatures.gmt")
    )
    #> Custom GMT file created successfully: C:\Users\梁颖妍\AppData\Local\Temp\RtmpM1v5zz/custom_demo_signatures.gmt

    cat("Exported GMT to:", exported_gmt, "\n")
    #> Exported GMT to: C:\Users\梁颖妍\AppData\Local\Temp\RtmpM1v5zz/ImmuneSigR_signatures.gmt
    cat("Created Custom GMT at:", custom_gmt, "\n")
    #> Created Custom GMT at: C:\Users\梁颖妍\AppData\Local\Temp\RtmpM1v5zz/custom_demo_signatures.gmt