A Protocol to Prepare files for GSEAPY

As a biological researcher, I like protocols, so as other researchers, too.

Here is an short tutorial to walk you through gseapy.

For file format explanation, please see here

In order to run gseapy successfully, install gseapy use pip.

pip install gseapy

# if you have conda
conda install -c bioconda gseapy

Use gsea command, or gsea()

Follow the steps blow.

One thing you should know is that the gseapy input files are totally the same as GSEA desktop required. You can use these files below to run GSEA desktop, too.

1. Prepare an tabular text file of gene expression like this:

RNA-seq,ChIP-seq, Microarry data are all supported.

Here is to see what the structure of expression table looks like, you don’t have to run commands below:

import pandas as pd
df = pd.read_table('./test/gsea_data.txt')

#or assign df to the parameter 'data'
0 SCARA3 6.287 6.821 6.005 2.525 1.911 1.500
1 POU5F1 11.168 11.983 10.469 7.795 7.911 6.174
2 CTLA2B 4.362 5.708 4.633 1.493 0.000 1.369
3 CRYAB 11.339 11.662 11.714 7.698 7.928 7.779
4 PMP22 7.259 7.548 6.803 4.418 2.239 3.071

2. An cls file is also expected.

This file is used to specify column attributes in step 1, just like GSEA asked.

An example of cls file looks like below.

with open('gsea/edb/C1OE.cls') as cls:

# or assign a list object to parameter 'cls' like this
# cls=['C1OE', 'C1OE', 'C1OE', 'Vector', 'Vector', 'Vector']
6 2 1
# C1OE Vector
C1OE C1OE C1OE Vector Vector Vector
The first line specify the total samples and phenotype numbers. Leave number 1 alway be 1.
The second line specify the phenotype class(name).
The third line specify column attributes in setp 1.

3. Gene_sets file in gmt format.

All you need to do is to download gene set database file from GSEA website.

Or you could use enrichr library. In this case, just provide library name to parameter ‘gene_sets’

If you would like to use you own gene_sets.gmts files, build such a file use excel, and then rename to gene_sets.gmt.

An example of gmt file looks like below:

with open('gsea/edb/gene_sets.gmt') as gmt:
ES-SPECIFIC Arid3a_used     ACTA1   CALML4  CORO1A  DHX58   DPYS    EGR1    ESRRB   GLI2    GPX2    HCK     INHBB
HDAC-UNIQUE     Arid3a_used 1700017B05RIK   8430427H17RIK   ABCA3   ANKRD44 ARL4A   BNC2    CLDN3
XEN-SPECIFIC        Arid3a_used     1110036O03RIK   A130022J15RIK   B2M     B3GALNT1        CBX4    CITED1  CLU     CTSH    CYP26A1
GATA-SPECIFIC       Arid3a_used     1200009I06RIK   5430407P10RIK   BAIAP2L1        BMP8B   CITED1  CLDN3   COBLL1  CORO1A  CRYAB   CTDSPL  DKKL1
TS-SPECIFIC Arid3a_used     5430407P10RIK   AFAP1L1 AHNAK   ANXA2   ANXA3   ANXA5   B2M     BIK     BMP8B   CAMK1D  CBX4    CLDN3   CSRP1   DKKL1   DSC2

4. Run gseapy inside python

At least 3 files are required to run gseapy.

interactive python console .. code:: python

import gseapy gseapy.gsea(data=’gsea_data.txt’, cls=’gsea.cls’, gmt=’gene_sets.gmt’, outdir=’gseapy_out’)

bash shell .. code:: bash

gseapy gsea -d gsea_data.txt -c test.cls -g gene_sets.gmt -o gseapy_out

Use prerank Command, or prerank()

If you would like to use a pre-ranked gene list to run GSEAPY, prerank module expects a pre-ranked gene list dataset with correlation values, which in .rnk format, and gene_sets file in gmt format. prerank module has the same API to GSEA pre-rank tools.

After this, you can start to run gseapy.

gseapy prerank -r gsea_data.rnk -g gene_sets.gmt -o test

Or run inside python.

import gseapy
gseapy.prerank(rnk='gsea_data.rnk', gene_sets='gene_sets.gmt', outdir='test')

Use ssgsea command, or ssgsea()

gseapy ssgsea -d expression.txt -g gene_sets.gmt -o test
gseapy.ssgsea(data="expression.txt", gene_sets= "gene_sets.gmt", outdir='test')

Use enrichr command, or enrichr()

The only thing you need to prepare is a gene list file.

Note: Enrichr uses a list of Entrez gene symbols as input.

For enrichr , you could assign a list object

# assign a list object to enrichr
l = ['SCARA3', 'LOC100044683', 'CMBL', 'CLIC6', 'IL13RA1', 'TACSTD2', 'DKKL1', 'CSF1',
     'SYNPO2L', 'TINAGL1', 'PTX3', 'BGN', 'HERC1', 'EFNA1', 'CIB2', 'PMP22', 'TMEM173']

gseapy.enrichr(gene_list=l, description='pathway', gene_sets='KEGG_2016', outfile='test')

or a gene list file in txt format(one gene id per row)

gseapy.enrichr(gene_list='gene_list.txt', description='pathway', gene_sets='KEGG_2016', outfile='test')

Let’s see what the txt file looks like.

with open('data/gene_list.txt') as genes:

Select the library you want to do enrichment analysis. For a view all avilable libraries,run

#s get_library_name(), it will print out all library names.
import gseapy
names = gseapy.get_library_name()

for for details, please track the offical links: http://amp.pharm.mssm.edu/Enrichr/

Use replot Command, or replot()

You may also want to use replot() to reproduce GSEA desktop plots.

The only input of replot() is the directory of GSEA desktop output.

The input directory(e.g. gsea), must contained edb folder, gseapy need 4 data files inside edb folder.The gsea document tree looks like this:


After this, you can start to run gseapy.

import gseapy
gseapy.replot(indir ='gsea', outdir = 'gseapy_out')

If you prefer to run in command line, it’s more simple.

gseapy replot -i gsea -o gseapy_out
For advanced usage of library,see the How to Use GSEAPY.