Setup and Run

Pipeline Configuration File (config)

The pipeline configuration file, config, sets the core parameters for running the pipeline, including:

  • Which modules to execute

  • Input Gene Expression Data file

  • Target species

  • Gene Expression samples mapping to control/treatment groups averaging

  • Conditions and thresholds to define differentially expressed genes

  • Data sources to perform Over-Representation Enrichment Analysis

  • Groups phenotypes for GSEA Classic

  • Preranked scoring metric/s of the Gene Expression Matrix for GSEA Preranked

  • Post-processing filtering parameters of the enrichment analysis results

Note

This file must be named config and placed in the assigned working directory (/data).

Variables defined in the config to setup the pipeline execution

Module #

Variable

Description

Example Possible Values

All

modules

Comma-separated string of modules indexes to run.

Mandatory and most important!

“1,2,3,4,5,6,7”

All

species

Target species (following the Organism List)

“Mouse” or “10090”

1, 5

input

Name of input gene expression data file (.tsv)

expression_matrix.tsv

1, 5

gene

Column index with Gene identifiers

1

1, 5

description

(Optional) Column index of the Gene description

2

1, 5

number_groups

Number of distinct groups (control and experimental/s)

2

1, 5

number_samples

Total number of samples across all groups

8

1, 5

samples

Comma-separated column indexes of samples

“3,4,5,6,7,8,9,10”

1, 5

group_order

Mapping of sample column indexes to groups. Important for GSEA association.

“Control 4 Exp 4”

1, 5

isoform

(Optional) Isoform filtering reference based on set group averages

Control

1, 5

calculate_averages

Compute group sample averages

true or false

1

condN

Set N filtering conditions/comparisons between groups.

cond1=”Exp/Control”

1

expression_min

Min threshold to classify genes as overexpressed

2

1

expression_max

Max threshold to classify genes as underexpressed

1

1

selected

(Priority) Column index to mark genes (value 1). Takes priority over conditions.

11

3

gprofiler_dbs

Comma-separated string of data sources for g:Profiler

REAC,GO:CC,GO:MF

4

panther_dbs

Comma-separated string of data sources for PANTHER

GO_SLIM_CC,GO:BP

5, 6

method

Select GSEA running mode

“classic” or “preranked”

5

prerankN

Custom formulas for preranked lists.

prerank1=”Exp/Control”

6

res*

(GSEA Parameter) Name of expression dataset (GCT/RES)

expression_dataset.gct

6

cls*

(GSEA Parameter) Name of phenotype labels file (CLS)

phenotype_labels.cls

6

rnk*

(GSEA Parameter) Name of preranked list file (RNK)

preranked_list.rnk

6

gmx*

(GSEA Parameter) Name of gene set file (GMT).

m2.all.v2026.1.Mm.gmt

6

collapse*

(GSEA Parameter) How gene identifiers are handled.

“No_Collapse” or “Collapse”

6

chip*

(GSEA Parameter) Optional chip annotation file.

6

permute*

(GSEA Parameter) Permutation type.

“phenotype” or “gene_set”

6

nperm*

(GSEA Parameter) Number of permutations.

1000

7

intersection

Compute the overlap between enriched terms from different tools.

true or false

7

max_annot

Max allowed enriched term size

500

7

min_coverage

Min gene coverage for term inclusion (0 to 1)

0.2

7

max_occur

Max occurrences of a gene across terms

20

Note: The GSEA Run Parameters for Module 6 are set by the pipeline when ran in combination with Module 5*

Example of config to run full pipeline, ORA and GSEA Preranked (# lines are comments):

# ---- Config file ----
# General parameters
modules="1,2,3,4,5,6,7"
species="Mouse"
input="expression_matrix.tsv"

# Module 1 and 5 input file handling
gene=1
description=2
number_groups=2
number_samples=8
samples="3,4,5,6,7,8,9,10"
groups="Control 4 Exp 4"
calculate_averages=true
isoform="Control"

# Module 1 calculated filtering conditions (e.g. fold-change) and set thresholds
cond1="Exp/Control"
cond2="Control/Exp"
expression_min=2

# Extract flagged (1) genes in column index 11 to list
# selected=11

# Modules 3 and 4 target source analysis
gprofiler_dbs="GOs,Reactome,WikiPathways,KEGG"
panther_dbs="GOs,Reactome,PantherPathways"

# Module 5 parameters for GSEA Preranked inputs preparation
method="preranked"
prerank1="Exp/Control"
prerank2="Control/Exp"

# Module 7 enrichment results intersection and filtering
intersection=true
max_annot=500
min_ratio=0.05
max_occur=5

Note

Modules 1 and 5 depend on the input data files defined in the config. All input files must be must placed correctly inside the mounted data directory /data.

Working directory structure (/data)

Example of a correctly populated data directory to run the full pipeline:

/data/
├── config
├── gene_sets/
|   └── m2.all.v2026.1.Mm.gmt
└── expression_matrix.tsv

Data files include the expression_matrix.tsv and m2.all.v2026.1.Mm.gmt (from the Molecular Signature Database).

Possible Entry Points

The pipeline’s modular design allows users to flexibly customize their analysis by running modules independently and supplying their own pre-prepared inputs at multiple stages. This makes it possible to:

  • Use custom gene lists (e.g., bypassing Module 1) for Enrichment Analysis

  • Use ready-made GSEA inputs for direct GSEA execution

  • Filter previously generated Enrichment results

Below, the accepted input formats and placement requirements are detailed for each relevant module.

Multiple Genes Lists for ORA

Purpose: Enables gene identifier mapping and enrichment analysis directly from one or more user-provided gene lists to selected ORA methods (g:Profiler and PANTHER).

Placement: Store the lists in a directory named /prepared_gene_lists inside the assigned working directory /data.

/data/
├── config
└── prepared_gene_lists/
    ├── custom_gene_list_1
    ├── custom_gene_list_2
    ├── custom_gene_list_3
    └── ...

Configuration: Define the mapping and enrichment analysis modules (modules), target species (species) and the target annotations sources of the analysis (gprofiler_dbs, panther_dbs) in the configuration file config.

Example configuration file:

# ---- Config file ----
# General parameters
modules="2,3,4"
species="Mouse"

# Modules 3 and 4 target source analysis
gprofiler_dbs="GOs,Reactome,WikiPathways,KEGG"
panther_dbs="GOs,Reactome,PantherPathways"

Note

Provided gene lists must pass through gene identifier mapping (Module 2) to ensure consistent enrichment analysis and terms annotations results.

To run analysis in all available annotation sources, leave the respective variable empty (gprofiler_dbs for g:Profiler; panther_dbs for PANTHER).

Running GSEA Preranked

Purpose: Run GSEA directly using pre-generated inputs (without the need of Module 5). Mutiple GSEA Preranked runs be done with multiple Preranked Gene Lists.

Placement for GSEA Preranked: Store the Preranked files in a directory named /preranked_lists inside the assigned working directory /data.

/data
├── config
├── preranked_lists/
|   ├── preranked_list_1.rnk
|   ├── preranked_list_2.rnk
|   ├── preranked_list_3.rnk
|   └── ...
└── gene_sets/
    ├── m2.all.v2026.1.Mm.gmt
    └── m5.all.v2026.1.Mm.gmt

Configuration: Define the GSEA module (modules), target species (species), the GSEA Preranked method (method) and respective inputs in the parameters (rnk, gmx) in the configuration file config.

Example configuration file for GSEA Preranked:

# ---- Config file ----
# General parameters
modules="6"
species="Mouse"

# Modules 6 GSEA run parameters
method="preranked"
rnk="preranked_list1.rnk"
gmx="m2.all.v2026.1.Mm.gmt"

Note

To run multiple consecutive GSEA Preranked runs with provided Preranked lists the user should leave the rnk variable empty. If set, only selected analyzed.

In the same way, to run GSEA with more than one gene set (provided inside the /gene_sets directory) the user should leave the gmx variable empty. If set, only selected is used in the analysis.

Running GSEA Classic

Purpose: Run GSEA Classic directly using pre-generated inputs (without the need of Module 5).

Placement for GSEA Classic: Files must be located in the set working directory /data.

/data
├── config
├── expression_dataset.gct  (or .res)
├── phenotype_labels.cls
└── /gene_sets
    ├── m2.all.v2026.1.Mm.gmt
    └── m5.all.v2026.1.Mm.gmt

Configuration: Define the GSEA module (modules), target species (species), the GSEA Classic method (method) and respective inputs in the parameters (res, cls, gmx) in the configuration file config.

Example configuration file for GSEA Classic:

# ---- Config file ----
# General parameters
modules="6"
species="Mouse"

# Modules 6 GSEA run parameters
method="classic"
res="expression_dataset.gct"
cls="phenotype_labels.cls"
gmx="m2.all.v2026.1.Mm.gmt"

Note

To run GSEA with more than one gene set (provided inside the /gene_sets directory) the user should leave the gmx variable empty. If set, only selected is used in the analysis.

Enrichment Results Filtering

Purpose: Filter and refine enrichment results from previous runs, produced by auto-Enrich.

Placement: Keep results in their default module-specific output directories inside /data, as generated by the pipeline.

/data/
├── gprofiler/
|   └── <gene_list>/
|       ├── enrichment_fields.tsv
|       ├── enriched_terms_annotations.tsv
|       └── /REAC/annotations/*
├── panther/
|   └── <gene_list>/
|       ├── enrichment_fields.tsv
|       ├── enriched_terms_annotations.tsv
|       └── /REAC/annotations/*
└── GSEA/results/
    └── <gsea_run>/
        ├── enrichment_fields.tsv
        ├── enriched_terms_annotations.tsv
        └── /REAC/annotations/*

Configuration: Define filtering parameters (intersection, max_annot, min_coverage, max_occur) in the configuration file config.

Example configuration file:

# ---- Config file ----
# General parameters
modules="7"
species="Mouse"

# Modules 7 EA filtering parameters
intersection=true
max_annot=500
min_coverage=0.05

Run Command

After filling in the configuration file and making sure the input files are present and correctly placed, the user should run the following command to use the Docker image of the pipeline:

docker run --rm -v /your/working/directory:/data pegi3s/auto_enrich

A mounted directory structure, where the user should change your/working/directory to their data directory.

Behavior

Modules are executed sequentially according to the tools variable in the config file, allowing flexible customization of the analysis flow.

The pipeline relies on standardized file naming conventions to detect outputs from previous modules, removing the need for manual re-specification of inputs. Internal state flags coordinate execution logic, while embedded sanity checks confirm the presence of required files and configurations, providing clear error reporting if issues arise.

  • Modules 1 → 2 (gene mapping):

When Module 1 generates gene lists from an expression matrix, Module 2 processes each list to map gene identifiers. This ensures that all lists are consistently annotated and aligned with the target species defined in config, for downstream enrichment analyses.

  • Modules 2 → 3/4 (gProfiler/panther):

Module 3 (g:Profiler) and Module 4 (PANTHER) require the mapped gene information file from Module 2. Running Module 2 beforehand is strongly recommended, since the correct species definition in config is also critical to both identifier mapping and the selection of the appropriate annotation sets.

  • Modules 5 → 6 (GSEA):

If Module 5 is executed, it prepares all necessary GSEA input files. Module 6 then runs either GSEA Classic or GSEA Preranked with the prepared inputs and sets the needed GSEA parameters files for the runs. When multiple pre-ranked lists are available, the pipeline iteratively runs GSEA for each. This setup supports fully automated batch GSEA analyses without manual reconfiguration.

Additional Flags

This section describes one additional flag that can be run at any time. These function operates on the enrichment analysis results.

Note

These flag must be set in the pipeline configuration file, config.

Reactome hierarchy

reac_hierarchy=true

  • Purpose

    Build a hierarchical tree of enriched Reactome pathways and adds a layer column to the results. The layer column indicates each pathway’s position within the Reactome hierarchy, helping users understand pathway relationships, hierarchical context, and the level of biological specificity represented by each enriched pathway.

  • Source

    Automatically uses results from the Reactome source directories (e.g. g:Profiler enrichment results):

    /gprofiler/results/REAC/enrichment_fields.tsv

    /gprofiler/results/REAC/enriched_terms_annotations.tsv

  • Output files (inside the REAC source directory)

    /gprofiler/results/REAC/

    • enriched_tree_ascii.pdf – Hierarchy tree of the enriched Reactome pathways (PDF).

    • enriched_tree_ascii.txt – Same tree in plain text (TXT).

  • Additional column (layer)

    A new column (layer) is added, to the end of the enrichment fields and enriched terms annotation files. It indicates the pathway’s hierarchical level:

    • 0 – Root level parent pathway

    • 1 – Second-level parent

    • 2 – Third-level parent

    • 3 – Fourth-level parent

    • …

    • n – Xth-level parent

Note

Only functional for gprofiler and panther results directories.