Package: blitzgsea
Installation|Example|Optional Parameters|Speed-up|Plotting|Attribution|ReferencesblitzGSEA IntroductionThis Python package provides a computationally performantGeneSetEnrichmentAnalysis (GSEA) implementation of the pre-rank algorithm [1]. GSEApy was used as the reference for the running sum and enrichment score calculation [2]. The algorithm estimates the enrichment score (ES) distribution of the null model by fitting data to gamma distibutions instead of calculating permutations for each gene set. blitzGSEA calculates p-values with much higher accuracy than other reference implementations available in Python.Gene set libraries can directly be loaded from Enrichr (https://maayanlab.cloud/Enrichr). For this use theblitzgsea.enrichr.get_library()function. All libraries can also be listed withblitzgsea.enrichr.print_libraries().blitzGSEA provides plotting functions to generate publication ready figures similar to the original GSEA-P software.blitzgsea.plot.running_sum()plots an enrichment plot for a single gene set andblitzgsea.plot.top_table()plots the topngene sets in a compact table.InstallationblitzGSEA is currently only available as a Python package in this GitHub repository. You can install the blitzGSEA Python package and its dependencies through pip by using the following command:$ pip install blitzgseaRun enrichment analysis using blitzGSEAblitzGSEA depends on two input files. 1) a gene signature and 2) a gene set library. The gene set library is a dictionary with the name of the gene set as key and a list of gene ids as values. Gene set libraries can be loaded directly from Enrichr. The signature should be a pandas dataframe with two columns [0,1]. The first column should contain the gene ids (matching the gene ids in the gene set library).Python exampleThis short example will download two files (signature and gene set library). The gene set library consists of KEGG pathways and the signature is an example signature of differential gene expression of muscle samples from young and old donors. Differential gene expression was computed with Limma Voom.importblitzgseaasblitzimportpandasaspd# read signature as pandas dataframesignature=pd.read_csv("https://github.com/MaayanLab/blitzgsea/raw/main/testing/ageing_muscle_gtex.tsv")# list available gene set libraries in Enrichrblitz.enrichr.print_libraries()# use enrichr submodule to retrieve gene set librarylibrary=blitz.enrichr.get_library("KEGG_2021_Human")# run enrichment analysisresult=blitz.gsea(signature,library)Example Inputindex011ADO-7.8334392CHUK-7.8009203GOLGA4-7.78722.........The gene set library is a dictionary with the gene set names as key and lists of gene ids as values.{'ERBB2 SIGNALING PATHWAY (GO:0038128)':['CDC37','PTPN12','PIK3CA','SOS1','CPNE3','EGF',...],'HETEROTYPIC CELL-CELL ADHESION (GO:0034113)':['DSC2','ITGAV','ITGAD','LILRB2',...],...}Optional ParametersThe main function ofblitzgsea.gsea()supports several optional parameters. The default parameters should work well for most use cases.parameter nametypedefaultdescriptionpermutationsint2000Number of randomized permutations to estimate ES distributions.min_sizeint5Minimum number of genes in geneset.max_sizeint4000Maximal number of genes in gene set.anchorsint20Number of gene set size distributions calculated. Remaining are interpolated.processesint4Number of parallel threads. Not much gain after 4 threads.symmetricboolFalseUse same distribution parameters for negative and positive ES. IfFalseestimate them separately.signature_cacheboolTrueCache precomputed anchor parameters in memory for later reuse.shared_nullboolFalseUse same null for signatures if a compatible model already exists. (uses KL-divergence test).kl_thresholdfloat0.3Controls how similar signature value distributions have to be for reuse.kl_binsint200Number of bins in PDF representation of distributions for KL test.plottingboolFalsePlot estimated anchor parametes.verboseboolFalseToggle additonal output.progressboolFalseToggle progress bar.seedint0Random seed. Same seed will result in identical result. If seed equal-1generate random seed.add_noiseboolFalseAdd small random noise to signature. The noise is a fraction of the expression values.centerboolTrueCenter signature values at 0 before calculating running sum.Speeding up enrichment calculationsblitzGSEA is currently the fastest GSEA implementation. The most time-consuming step of blitzGSEA is the generation of a robust null distribution to compute p-values. Since the null distribution depends on the value distribution of the input signature, blitzGSEA will, by default, compute a new null for each new input signature. blitzGSEA can compute the similarity between input signatures using Kullback–Leibler divergence to identify similar signatures to share null models. A cached null model is used if a previous signature has a similar value distribution. The relevant parameters of theblitzgsea.gsea()function are shown below:parameter nametypedefaultdescriptionsignature_cacheboolTrueCache precomputed anchor parameters in memory for later reuse.shared_nullboolFalseUse same null for signatures if a compatible model already exists. (uses KL-divergence test).kl_thresholdfloat0.3Controls how similar signature value distributions have to be for reuse. The smaller the more conservative.kl_binsint200Number of bins in PDF representation of distributions for KL test.Exampleimportblitzgseaasblitzimportpandasaspd# read signature as pandas dataframesignature=pd.read_csv("https://github.com/MaayanLab/blitzgsea/raw/main/testing/ageing_muscle_gtex.tsv")# run enrichment analysisresult=blitz.gsea(signature,library,shared_null=True)Plotting enrichment resultsblitzGSEA supports several plotting functions.blitzgsea.plot.running_sum()andblitzgsea.plot.top_table()can be used after enrichment has been performed.blitzgsea.plot.running_sum()shows the running sum of an individual gene set. It has acompactmode in which the image will be more readable if small.blitzgsea.plot.top_table()shows the topnenriched gene sets and displays the results in a table, with normalized enrichment score (NES) and the distribution of hits relative to the gene ranking of the signature.Exampleimportblitzgseaasblitzimportpandasaspd# read signature as pandas dataframesignature=pd.read_csv("https://github.com/MaayanLab/blitzgsea/raw/main/testing/ageing_muscle_gtex.tsv")# use enrichr submodule to retrieve gene set librarylibrary=blitz.enrichr.get_library("KEGG_2021_Human")# run enrichment analysisresult=blitz.gsea(signature,library)# plot the enrichment results and save to pdffig=blitz.plot.running_sum(signature,"Cell adhesion molecules",library,result=result,compact=False)fig.savefig("running_sum.png",bbox_inches='tight')fig_compact=blitz.plot.running_sum(signature,"Cell adhesion molecules",library,result=result,compact=True)fig_compact.savefig("running_sum_compact.png",bbox_inches='tight')fig_table=blitz.plot.top_table(signature,library,result,n=15)fig_table.savefig("top_table.png",bbox_inches='tight')# disable switching of interactive plotting, which can cause issues in jupyter notebooks# will plot the figure into the notebookfig=blitz.plot.running_sum(signature,"Cell adhesion molecules",library,result=result,compact=False,interactive_plot=True)fig_table=blitz.plot.top_table(signature,library,result,n=15,interactive_plot=True)The resulting plots will look like the examples below:running_sum.pdfrunning_sum_compact.pdftop_table.pdfSample shufflingThis is the sample shuffling algorithm from GSEApy. It performs a t-test to build signatures for phenotype shuffled groups. The input is a gene expression dataframe, which should be normalized for library size.groupsis a list containing 0 or 1 describing the corresponding group for the samples inexprs. The index ofexprsare the gene ids matching the gene set library.blitz.shuffle.gsea(exprs,library,groups,permutations=50,seed=1)parameter nametypedefaultdescriptionexprspd.DataFrameNANormalized gene expression matrix.librarydictionaryNAGene set library.groupslistNAPhenotype group labels of samples. Labels are 0 or 1.permutationsint1000Number of permutations.seedint1Random state seed.DependenciesPython 3.6+AttributionThe statistical tool was developed by theMa'ayan Laboratory. When using blitzgsea please cite the following reference:Lachmann, Alexander, Zhuorui Xie, and Avi Ma’ayan. "blitzGSEA: efficient computation of gene set enrichment analysis through gamma distribution approximation." Bioinformatics (2022).https://academic.oup.com/bioinformatics/advance-article/doi/10.1093/bioinformatics/btac076/6526383?login=falseReferences[1] Lachmann, Alexander, Zhuorui Xie, and Avi Ma’ayan. "blitzGSEA: efficient computation of gene set enrichment analysis through gamma distribution approximation." Bioinformatics (2022).[2] Subramanian, Aravind, Heidi Kuehn, Joshua Gould, Pablo Tamayo, and Jill P. Mesirov. "GSEA-P: a desktop application for Gene Set Enrichment Analysis." Bioinformatics 23, no. 23 (2007): 3251-3253.[3] Fang, Zhuoqing, Xinyuan Liu, and Gary Peltz. "GSEApy: a comprehensive package for performing gene set enrichment analysis in Python." Bioinformatics (2022).