Description

Module 1: Prepare Gene Lists

This module automates the extraction of over- or under-expressed gene lists from an expression matrix. It applies user-defined thresholds and conditions to identify differentially expressed genes across experimental groups.

Purpose

Standardize the creation of input gene lists for downstream Over-Representation Enrichment Analyses (ORA).
Generate lists of over- and under-expressed genes based on configurable conditions and thresholds.

Inputs:

Expression matrix (tab-separated values) containing gene identifiers (either Gene IDs, UniProtKB IDs or Gene Symbols) and expression values.
Configuration file (config) with user-defined variables from table below.

Important

Inputs must be placed in the in the assigned working directory (/data).

Variables defined in config required for Module 1

Variable	Description	Example Possible Values
input	Indicate the name of input gene expression data file (tab-separated values).	expression_matrix.tsv
gene	Indicate the column index with the Gene identifiers (Entrez GeneIDs, UniProtKB IDs or Gene Symbols).	1
description	(Optional) Column index of the Gene description.	2
number_groups	Indicate the number of distinct groups (control and experimental/s).	2
number_samples	Indicate the total number of samples across all groups.	8
samples	Indicate the column indexes of samples in the input gene expression file.	3,4,5,6,7,8,9,10
group_order	Set the mapping between indicated samples columns and their respective groups.	Control 4 Exp 4
isoform	(Optional) Indicate the base reference group, as indicated in the variable ‘group_order’, for isoform filtering	Control
calculate_averages	Set if group samples averages should be calculated (based on set ‘samples’ and ‘group_order’).	true or false
condN	Set N comparisons between groups, such as the fold-change between two groups.	cond1=”Exp/Control” and cond2=”Control/Exp”
expression_min	Set the minimum threshold of calculated conditions to classify genes as overexpressed.	2
expression_max	Set the maximum threshold of calculated conditions to classify genes as underexpressed.	1
selected	(Priority) Indicate the column index containing pre-evaluated gene with binary values (1/0) for gene extraction into a list.	11

Warning

Column index starts at 1
If both expression_min and expression_max are defined, only genes within the range are included.
The select parameter takes priority over all other rules: only genes with the value 1 in the specified column will be kept.

Outputs:

Gene lists of over- or under-expressed inside a directory named /prepared_gene_lists

Note

For more details, see the Module 1 Outputs section.

Module 2: Map Gene Identifiers

This module standardizes a list of Gene identifiers into a unified format to ensure compatibility across enrichment tools and biological databases. By harmonizing identifiers, it enables accurate cross-referencing and smoother downstream integration.

Inputs:

A list/s of Gene identifiers of GeneIDs, UniprotKB IDs or Gene Symbols (one per line).

Outputs:

TSV file/s with one gene per row, including:
- Entrez Gene ID
- UniProtKB ID
- HGNC Gene Symbol
- Full Gene Name
- Species Name
Species-specific cache file, storing retrieved mappings to speed up future runs.

Note

For more details, see the Module 2 Outputs section.

Module 3: gProfiler plus

This module automates enrichment analysis using the g:Profiler g:GOSt tool via its API. It handles sending requests across all or user-selected annotations sources, applying False Discovery Rate (FDR) correction, formatting outputs, and mapping enriched terms annotations.

Supported annotation sources:

CORUM – Manually annotated protein complexes from mammalian organisms.
GO:MF – Gene Ontology Molecular Function branch
GO:BP – Gene Ontology Biological Process branch
GO:CC – Gene Ontology Cellular Component branch
HPO – Human Phenotype Ontology, a standardized vocabulary of phenotypic abnormalities encountered in human disease.
HPA - Human Protein Atlas expression data
miRNA – mirTarBase miRNA targets
REAC – Reactome pathways
WP – WikiPathways
KEGG* – KEGG pathways
TRANSFAC* – Transfac transcription factor binding site predictions

Note

KEGG and TRANSFAC are omitted datasources from the terms annotations results file due to licensing issues when downloading and assembling the GMT file archive.

Input/s:

Mapped gene list/s (tab-separated file as generated by Module 2), inside a folder named prepared_gene_lists containing:
- Entrez Gene ID
- UniProtKB ID
- HUGO Gene Symbol
- Full Gene Name
- Species Name
Module configuration variables (defined in config):
```
modules=3
species=
gprofiler_dbs=
```

species: Specify the target species of the analysis. Consult the Organism List as used by g:Profiler.

The display name, scientific name and id can be used, additionally the Species TaxonID can also be used.

gprofiler_dbs: Lists the annotation sources to include for enrichment (e.g., GO:BP, GO:MF, KEGG, Reactome). Leave empty to include all sources (default) .

Available database keys for gprofiler_dbs (in config)

Source	Possible Keys (only use one)
GO:CC	GO:CC \| GO_CC \| GO CC
GO:BP	GO:BP \| GO_BP \| GO BP
GO:MF	GO:MF \| GO_MF \| GO MF
GO:CC & GO:BP & GO:MF	GOS
REAC	REAC \| REACTOME \| REACTOME_PATHWAY \| REACTOME PATHWAY
KEGG*	KEGG \| KEGG PATHWAYS \| KEGG PATHWAY \| KEGG_PATHWAY \| KEGG_PATHWAYS
WP	WP \| WIKI PATHWAYS \| WIKI PATHWAY \| WIKI_PATHWAY \| WIKI_PATHWAYS
TF*	TF \| TRANSFAC
MIRNA	MIRNA \| MIRTARBASE
HPA	HPA \| HUMAN PROTEIN ATLAS \| HUMAN_PROTEIN_ATLAS
CORUM	CORUM
HP	HP \| HUMAN PHENOTYPE ONTOLOGY \| HUMAN_PHENOTYPE_ONTOLOGY

KEGG and TRANSFAC are omitted datasources from the terms annotations results file due to licensing issues when downloading and assembling the GMT file archive.

Outputs:

Results files (TSV) — combining all requested sources:

enrichment_fields.tsv → full enrichment fields (TermIDs, description, p-value, recall, precision, parents, etc.).
enriched_terms_annotations.tsv → consolidated summary of enriched terms annotations, counts, gene memberships and intersections (gene symbols)

Per-source subdirectories contain the same outputs restricted to that source, plus per-term annotation directories with:

genes_in_intersection → input genes that intersect with the genes in the enriched term
genes_in_term → full enriched term annotations genes (gene symbols)

Additionally (saved in the annotations directoy):

Note

For more details, see the Module 3 Outputs section.

Module 4: PANTHER plus

This module performs functional enrichment analysis using the PANTHER Classification System via its API. It runs statistical over-representation tests across all or user-selected annotations sources and to all available, applying False Discovery Rate (FDR) correction to ensure reliability of the reported terms.

Supported annotation sources:

Gene Ontology (Biological Process, Molecular Function, Cellular Component)
Manually Curated Gene Ontology SLIM subset
Reactome Pathways
PANTHER Pathways
PANTHER Protein Class Ontology

Input/s:

Mapped gene list/s (tab-separated file as generated by Module 2), inside a folder named prepared_gene_lists containing:
- Entrez Gene ID
- UniProtKB ID
- HUGO Gene Symbol
- Full Gene Name
- Species Name
Module configuration variables (defined in config):
```
modules=4
species=
panther_dbs=
```

species: Specify the target species of the analysis, same as used by g:Profiler on Organism List.: The display name, scientific name and id can be used, additionally the Species TaxonID can also be used.

Important

PANTHER does not support all the same species as g:Profiler. Please consult https://www.pantherdb.org/panther/summaryStats.jsp to see the 144 species convered by PANTHER.

g:Profiler species nomenclature still stands when setting up the species variable (even when just using PANTHER).

panther_dbs: Lists the annotation sources to include for enrichment (e.g., GO:BP, GO:MF, Reactome). Leave empty to include all sources (default) .

Available database keys for panther_dbs (in config)

Source	Possible Keys (only use one)
GO:CC	GO_CC \| GO:CC \| GO CC
GO:BP	GO_BP \| GO:BP \| GO BP
GO:MF	GO_MF \| GO:MF \| GO MF
GO:CC & GO:BP & GO:MF	GOS
REAC	REAC \| REACTOME \| REACTOME_PATHWAY \| REACTOME PATHWAY
PTR_GO_SLIM_CC	GO_SLIM_CC \| GO:SLIM:CC \| PANTHER_GO_CC \| PANTHER GO CC \| PANTHER GO:CC \| PANTHER GO SLIM CC
PTR_GO_SLIM_BP	GO_SLIM_BP \| GO:SLIM:BP \| PANTHER_GO_BP \| PANTHER GO BP \| PANTHER GO:BP \| PANTHER GO SLIM BP
PTR_GO_SLIM_MF	GO_SLIM_MF \| GO:SLIM:MF \| PANTHER_GO_MF \| PANTHER GO MF \| PANTHER GO:MF \| PANTHER GO SLIM MF
PANTHER_PATHWAY	PANTHER_PATH \| PANTHER PATH \| PANTHER_PATHWAY \| PANTHER PATHWAY
PANTHER_PC	PANTHER_PC \| PANTHER PC \| PANTHER_PC

Outputs:

Results files (TSV) — combining all requested sources:

enrichment_fields.tsv → full enrichment fields (TermIDs, description, p-values, fold enrichment, etc.)
enriched_terms_annotations.tsv → consolidated summary of enriched terms annotations, counts, gene memberships and intersections (gene symbols)
- enriched_terms_annotations_pos.tsv → positive enriched terms annotations (+)
- enriched_terms_annotations_neg.tsv → negative depleted terms annotations (-)

Per-source subdirectories contain the same outputs restricted to that source, plus per-term annotation directories with:

genes_in_intersection → input genes that intersect with the genes in the enriched term
genes_in_term → full enriched term annotations genes (gene symbols)

Additionally annotation source files (from PANTHER, GO and Reactome) are saved in the annotations directoy.

Note

For more details, see the Module 4 Outputs section.

Module 5: Prepare GSEA inputs

This module automates the creation of input files required for Gene Set Enrichment Analysis (GSEA). Its able to handle group samples averaging, isoform filtering, prerank evaluation and file formatting. It transforms a gene expression matrix into the proper formats for either:

GSEA Classic – uses expression matrices to compare predefined experimental groups (called phenotypes).
GSEA Preranked – uses preranked gene lists (ordered by score metric)

Inputs

Expression matrix (tab-separated values) containing gene identifiers (either Gene IDs, UniProtKB IDs or HGNC Gene Symbols) and expression values.
Configuration file (config) with user-defined variables from table below.

Important

Inputs must be placed in the in the assigned working directory (/data).

Variables defined in config required for Module 5

Variable	Description	Example Possible Values
input	Indicate the name of input gene expression data file (tab-separated values)	expression_matrix.tsv
gene	Indicate the column index with the Gene identifiers (Entrez GeneIDs, UniProtKB IDs or Gene Symbols)	1
description	(Optional) Column index of the Gene description	2
number_groups	Indicate the number of distinct groups (control and experimental/s).	2
number_samples	Indicate the total number of samples across all groups	8
samples	Indicate the column indexes of samples in the input gene expression file	3,4,5,6,7,8,9,10
group_order	Set the mapping between indicated samples columns and their respective groups	Control 4 Exp 4 (columns 3 to 6 are Control and columnss 7 to 10 are Exp)
isoform	(Optional) Indicate the base reference group, as indicated in the variable ‘group_order’, for isoform filtering	Control
calculate_averages	Set if group samples averages should be calculated (based on set ‘samples’ and ‘group_order’)	true or false
prerankN	Set N scoring metrics (like fold-change) using the indicated group names. Values are log2-transformed for consistency. One preranked list is created per set variable	prerank1=’Exp/Control’ and prerank2=’Control/Exp’
method	Select GSEA mode inputs should be prepared for	‘classic’ or ‘preranked’

Warning

Column indexes are 1-based.
Group order and samples count must match the order of samples listed in the variable samples.

Outputs:

For GSEA Classic

Formatted expression GCT dataset (.gct)
Phenotype labels CSL file (.cls)

For GSEA Preranked

Preranked gene lists generated from user-defined preranked scoring metrics (One or more .rnk files)

One individual preranked gene list is generated for each defined scoring metric (in the variable prerankN)

Note

For more details, see the Module 5 Outputs section.

Module 6: GSEA plus

This module integrates the Gene Set Enrichment Analysis (GSEA) workflow by wrapping the gsea-cli.sh tool (GSEA v4.4.0, Broad Institute). It automates file handling, parameter setup and results parsing, making it easier to run GSEA Classic or GSEA Preranked analyses.

Warning

Gene Set Enrichment Analysis are only available with Human and Mouse datasets!

Inputs:

Configuration file (config) with user-defined parameters from table below.

Data files:

Expression dataset (.gct or .res) and phenotype labels (.cls) for GSEA Classic

Preranked gene list (.rnk) for GSEA Preranked

Files must be provided insdie a directory named preranked_lists

Gene set/s (.gmt, .gmx, or .grp)

Files must be provided insdie a directory named gene_sets

Chip annotation file (.chip) - Optional

Important

Inputs must be placed in the in the assigned working directory (/data).

Key parameters that can be defined in the config file to run GSEA

Key	Description	Example Possible Values
species	Target species	Human or Mouse
method	Select GSEA running mode	classic or preranked
res	Indicate the name of the expression dataset file (GCT or RES format). Mandatory for GSEA Classic.	expression_dataset.gct
cls	Indicate the name of the phenotype labels file (CLS format), which can define either categorical phenotypes (e.g., tumor vs normal) or continuous phenotype. Mandatory for GSEA Classic.	phenotype_labels.cls
rnk	Indicate the name of the preranked gene list file. Mandatory for GSEA Preranked. Alternatively: One or more preranked files can be analyzed for analysis inside a directory named `preranked_lists`.	preranked_list.rnk
gmx	Indicate the name of the gene set file (GMT format), such as those provided by Molecular Signature Database. Alternatively: Must be put inside a directory named `gene_sets`. Leave variable empty to include more than one gene set provided.	m2.all.v2026.1.Mm.symbols.gmt from Mouse collections
collapse	Define how gene identifiers are handled: Collapse (default): Use the chip file to convert to gene symbols. No_Collapse: Use gene symbols as-is; no chip file needed. Remap_Only: Remap identifiers without collapsing data. Note: The pipeline utilizes these GSEA feature to automatically convert standard input gene identifiers into the same gene symbols. Leave empty to utilize this. If filled, the user-set collapse option is used.	No_Collapse
chip	(Optional) Indicate the name of the chip annotation file that maps array probe IDs to gene symbols. Required if `collapse` is manually set to ‘Collapse’ or ‘Remap_Only’.
permute	Define the permutation type: phenotype: Used in GSEA Classic. Shuffles sample labels. Recommended for datasets with ≥7 samples per group. gene_set: Used in GSEA Preranked. Randomizes gene sets.	gene_set
nperm	Define the number of permutations for statistical significance. The recommended value is 1000 (default), and 10 to test the setup.	1000

Tip

If GSEA is run sequentially after Module 5 (Prepare GSEA inputs), the pipeline automatically configures the necessary parameters for the GSEA run.

Note

Gene sets file (GMX) - Contains one or more gene sets. For each gene set, it gives the gene set name and list of features (genes or probes) in that gene set. Features can be downloaded in either Entrez Gene IDs or Gene Symbols identifiers. Format is GMX, GMT or GRP and can be individually downloaded from Human MSigbDB Collections or Mouse MSigDB Collections. Its recommended to use Gene Symbols identifiers files.
Collapse parameter - Since the default value of collapse is ‘Collapse’ it’s advised to set the parameter value yourself. If not set, GSEA falls to the default value which requires the chip annotation file, leading to an error if not provided.
Chip annotations files (CHIP) - Lists each identifier on a platform and its matching HGNC Gene Symbol. Optional for Gene Set Enrichment Analysis. CHIP format can be downloaded from the GSEA Downloads Chip Annotations files.

Additional parameters

This module supports nearly all options from the GSEA CLI, including:

metric, scoring_scheme, sort, set_max, set_min, norm, rnd_seed, zip_report, create_svgs, and others.

Note

See the GSEA User Guide for a complete reference GSEA User Guide.

Outputs:

Results files (TSV) — combining all requested sources:

enrichment_fields.tsv → full enrichment fields (TermIDs, description, p-values, fold enrichment, parent terms, etc.).
enriched_terms_annotations.tsv → consolidated summary of enriched terms annotations, counts, gene memberships and intersections (gene symbols)

Per-source subdirectories contain the same outputs restricted to that source, plus per-term annotation directories with:

genes_in_intersection → input genes that intersect with the genes in the enriched term
genes_in_term → full enriched term annotations genes (gene symbols)

raw_GSEA_output.zip — Contains the original GSEA output, including: HTML visual reports, enrichment plots, statistics and supporting files generated by the native GSEA tool

Note

For more details, see the Module 6 Outputs section.

Module 7: Filter EA results

This module filters enrichment analysis (EA) results to remove overly common or biologically unspecific terms and genes. It applies user-defined thresholds to refine the final annotations, retaining only the most relevant associations for downstream interpretation.

Inputs:

Enrichment analysis results directories (as produced by the pipeline)
At least one filtering parameter, from table below, defined in the configuration file (config).

Important

Inputs must be placed in the in the assigned working directory (/data).

Variables defined in the config to control execution of Module 7

Variable	Description	Example
intersection	Enables intersection analysis. If set to `true`, it identifies terms and genes enriched across multiple analysis within the same run.	true
max_annot	Sets the upper limit for the size of an enriched term (number of genes). Terms containing more genes than this value are filtered out.	500
min_coverage	Set the minimum fraction (0.0 to 1.0) of input genes that must be present in an enriched term relative to the total genes annotated to that term. Terms with lower coverage are excluded.	0.15
max_occur	Sets the maximum number of enriched terms a single gene can participate in. Genes appearing in more terms than this threshold are removed from the genes_in_list column of the results file.	10

Outputs:

From filtering thresholds (max_annot, min_coverage, max_occur):

filtered_enrichment_fields.tsv – A filtered version of enrichment fields results file with only the most relevant and specific retained categories. This file is saved inside the enrichment results directory of each tool.
filtered_enriched_terms_annotations.tsv – A filtered version of enriched term annotations results file with only the most relevant and specific retained categories. This file is saved inside the enrichment results directory of each tool.

From intersection analysis:

Inside a directory named common_results generated in the assigned working directory (/data).

Note

For more details, see the Module 7 Outputs section.

Example:

Suppose an enrichment results file contains:

Term GO:0016477 (cell migration) annotated with 975 genes.
Term GO:0034331 (cell junction maintenance) where 13 of 86 annotated genes are in the user’s input list (coverage = 0.1512).
Term GO:0071709 (membrane assembly) where 8 of 57 annotated genes are in the user’s input list (coverage = 0.1404).
Gene TP53 (an input gene) appearing in 15 enriched terms.

With the following parameters:

max_annot=500
min_coverage=0.15
max_occur=10

The filtering would:

Exclude GO:0016477 because its size (975) is over 500, but keep the GO:0034331 and GO:0071709 since their size (86 and 57) are under 500
Exclude GO:0071709 since its coverage (0.1404) is under 0.15, but keep the GO:0034331 since its coverage (0.1512) is above 0.15
Remove TP53 from all enriched terms, since it occurs in 15 terms, exceeding the limit (10)

Only terms and gene associations passing all active filters remain in the final output.

Hint

The best thresholds depend on the dataset and research goal. Users should first inspect unfiltered results to identify suitable cutoffs.