> For the complete documentation index, see [llms.txt](https://docs.owkin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.owkin.com/explore-and-analyse-data/data-analysis/expression-molecular-profiles/pathway-signature-enrichment.md).

# Pathway & signature enrichment

Assess pathway and gene-signature enrichment in sample or single-cell expression profiles, or in ranked gene lists, using ssGSEA or preranked GSEA.

Assess pathway and gene-signature enrichment in sample or single-cell expression profiles, or in ranked gene lists, using ssGSEA or preranked GSEA.

## ssGSEA — single-sample Gene Set Enrichment Analysis

### Description

#### Analysis summary

Computes a single enrichment score per scoring unit (a sample, or an individual cell on single-cell data) for each gene signature, summarising how highly the signature's genes rank in that unit's expression profile. Scores are comparable across units; gene signatures can be supplied manually or drawn from a curated pathway database to score named pathways rather than only hand-picked gene lists.

#### Computation

Runs single-sample GSEA via the gseapy library (<https://gseapy.readthedocs.io/en/latest/>): for each scoring unit (a bulk sample, a pseudo-bulk group, or an individual cell), the genes are ranked by expression and a weighted Kolmogorov–Smirnov-like enrichment score is integrated for each gene set. Output: one row per (scoring unit, gene set \[, stratum]) carrying the enrichment score, the signature's size and how many of its members were actually present in the expression matrix — when fewer were present, the score was computed on only that subset. Descriptive stats summarise the scores per signature (and per stratum when the data is stratified); pairwise statistical tests compare the scores between signatures, within each stratum when present.

#### When to use

Use for pathway/signature-activity questions per unit: is a cytotoxicity or interferon program higher in responders than non-responders, which immune signatures distinguish patient groups, or — scoring per cell — what a gene set's activity is within one cell type. For a supplied ranking (e.g. a differential-expression result) rather than raw expression, use the gsea mode instead.

#### Caveats

Per-cell scoring materialises a dense genes × units matrix and is refused beyond a size cap — score per cell type or pseudo-bulk instead of the whole tumour cell by cell. Signatures with no member in the expression matrix are skipped (reported); a signature covering the entire gene matrix has no ranking background and is also skipped. A gene missing for a unit counts as zero expression.

gseapy — the GSEA / pathway-enrichment Python toolkit this analysis runs through. Website: <https://gseapy.com/> — documentation: <https://gseapy.readthedocs.io/en/latest/> — paper: <https://pmc.ncbi.nlm.nih.gov/articles/PMC9805564/>.

### Example questions

<details>

<summary><code>example questions</code></summary>

* Single-sample enrichment score of a cytotoxic-T-cell signature across Bladder patient, grouping by responders vs non-responders in a violin plot
* ssGSEA scores of multiple immune signatures in Ovarian cancer, shown as a boxplot with one box per signature
* Per-cell ssGSEA activity of an interferon-response signature in B cells, comparing scores across indications in a violin plot

</details>

### Input columns

<details>

<summary><code>input columns</code></summary>

| column      | type        | required | description                                                                                                                                                      |
| ----------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| index       | any         | optional | ssGSEA: sample/cell/patient identifier — the unit at which enrichment scores are computed (required). gsea (preranked): not used; the ranking is global. A sing… |
| value       | numeric     | required | ssGSEA: numeric expression (e.g. TPM, log-norm count, intensity) used to rank genes within each sample. gsea (preranked): the signed per-gene ranking metric su… |
| x\_group    | categorical | required | Gene name (or other feature label) to be matched against the `members` field of each `gene_sets[i]`. Collapsed into the signature label in the output.           |
| y\_group    | categorical | optional | ssGSEA only: optional stratifier (e.g. clinical variable) kept untouched in the output, used for between-group comparison of enrichment scores. gsea (preranked… |
| patient\_id | any         | required | Patient identifier. Always required. ssGSEA: used for paired statistical tests. gsea (preranked): not used by the scoring itself — supply a single constant (e.… |

</details>

### Visualizations

* `violin` How to read: Each violin is one signature's distribution of enrichment scores across scoring units (side-by-side by the strata variable when the data is stratified). Significance brackets with stars mark groups with at least one significant pairwise comparison after multiple-testing correction (★ p<0.05, ★★ p<0.01, ★★★ p<0.001, ★★★★ p<0.0001). Higher scores mean the signature's genes rank more highly in that unit's expression profile.
* `boxplot` How to read: Each box is one signature's distribution of enrichment scores across scoring units (the centre line is the median, the box the middle half); side-by-side boxes are keyed by the strata variable when the data is stratified. Significance brackets with stars mark groups with at least one significant pairwise comparison after multiple-testing correction (★ p<0.05, ★★ p<0.01, ★★★ p<0.001, ★★★★ p<0.0001). Higher scores mean the signature's genes rank more highly in that unit's expression profile.
* `heatmap` How to read: Rows are scoring units, columns are signatures, and cell colour is the enrichment score (centred on 0 — see the colour bar); with sorting enabled the highest scores gather top-left. Read it as which unit carries which signature's activity; on single-cell data each row is one filtered cell population.

### Example analysis 1

#### Name — ssGSEA Signature Enrichment in TCGA Bladder Patients by Gender

#### Analysis parameters

<details>

<summary><code>analysis_name, analysis_params, viz_params</code></summary>

```json
{
  "analysis_name": "enrichment_analysis",
  "analysis_params": {
    "method": "ssgsea",
    "gene_sets": [
      {
        "members": [
          "CD8A",
          "GZMB",
          "PRF1",
          "GZMA",
          "NKG7"
        ],
        "label": "Cytotoxic"
      },
      {
        "members": [
          "ERBB2",
          "ROR1"
        ],
        "label": "ERBB2_ROR1"
      }
    ],
    "alpha": 0.25,
    "score": "nes"
  },
  "viz_params": {
    "plot_name": "violin",
    "index_label": "Sample",
    "x_group_label": "Signature",
    "value_label": "ssGSEA Enrichment Score",
    "y_group_label": "Gender",
    "title": "ssGSEA Signature Enrichment in TCGA Bladder Patients by Gender"
  }
}
```

</details>

#### Visualization — `violin`

![ssGSEA Signature Enrichment in TCGA Bladder Patients by Gender](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-bdb0f9d0556f18d7f7a1b1a48fe9697ffc825553%2Fenrichment_analysis__ssgsea__violin.png?alt=media)

#### Output table

<details>

<summary><code>descriptive_stats</code> (4 rows)</summary>

| x\_group    | y\_group | n   | mean     | std     | min      | p10     | p25     | p50      | p75     | p90    | max    |
| ----------- | -------- | --- | -------- | ------- | -------- | ------- | ------- | -------- | ------- | ------ | ------ |
| Cytotoxic   | female   | 118 | -0.03141 | 0.2126  | -0.3983  | -0.2742 | -0.2187 | -0.07438 | 0.1277  | 0.2812 | 0.4842 |
| Cytotoxic   | male     | 315 | -0.05192 | 0.2298  | -0.4106  | -0.2971 | -0.229  | -0.1087  | 0.07819 | 0.306  | 0.5894 |
| ERBB2\_ROR1 | female   | 118 | 0.2142   | 0.04826 | -0.02029 | 0.153   | 0.193   | 0.2253   | 0.2412  | 0.2624 | 0.2995 |
| ERBB2\_ROR1 | male     | 315 | 0.223    | 0.0486  | -0.02415 | 0.154   | 0.2113  | 0.2298   | 0.2485  | 0.2719 | 0.3922 |

</details>

<details>

<summary><code>statistical_tests</code> (2 rows)</summary>

| Test used for pairwise comparison | Group      | Contrast       | Statistic | Mean Difference | Higher Group | P-value | Adjusted P-value | Significance level | comparison\_a | comparison\_b |
| --------------------------------- | ---------- | -------------- | --------- | --------------- | ------------ | ------- | ---------------- | ------------------ | ------------- | ------------- |
| wilcoxon                          | ERBB2 ROR1 | (Female, Male) | 16380.0   | -0.00881        | Male         | 0.05748 | 0.115            |                    | female        | male          |
| wilcoxon                          | Cytotoxic  | (Female, Male) | 20050.0   | 0.02051         | Female       | 0.2053  | 0.2053           |                    | female        | male          |

</details>

## GSEA — classical preranked Gene Set Enrichment Analysis

### Description

#### Analysis summary

Runs classical preranked GSEA on a single ranked gene list (genes ordered by any signed metric you provide — fold change, a statistic, a correlation) against gene-set signatures, returning one normalised enrichment score (NES) per signature with its significance. Positive NES = enriched at the top of the ranking, negative = at the bottom. Gene signatures can be supplied manually or drawn from a curated pathway database.

#### Computation

One ranked gene list — genes with a signed ranking metric the caller supplies — is scored against every gene set via the gseapy library's prerank implementation (<https://gseapy.readthedocs.io/en/latest/>); the analysis does not compute the ranking metric itself and is not tied to differential expression. Output: one row per gene set with the normalised enrichment score (or the raw one), its nominal permutation p-value and Benjamini–Hochberg FDR, the signature's size and how many of its members were present in the ranked list, and the leading edge — the members that drive the enrichment, i.e. those ranked up to the peak of the running enrichment score — with its size and two concentration diagnostics: how much of the matched membership falls in the leading edge, and where the enrichment-score peak sits along the ranking (a small percentage = the peak is near the top).

#### When to use

Use when the input is already a ranking — a tumour-vs-normal differential-expression result, a correlation profile — and the question is which pathways/signatures are enriched at its top or bottom. For scoring raw expression per sample or per cell, use the ssgsea mode instead.

#### Caveats

Provide a single ranking: several rankings in one call are rejected (per-comparison multi-ranking is not yet supported). Genes duplicated in the list are averaged, and genes absent from the list simply do not count toward a signature's matched members.

gseapy — the GSEA / pathway-enrichment Python toolkit this analysis runs through. Website: <https://gseapy.com/> — documentation: <https://gseapy.readthedocs.io/en/latest/> — paper: <https://pmc.ncbi.nlm.nih.gov/articles/PMC9805564/>.

### Example questions

<details>

<summary><code>example questions</code></summary>

* Preranked GSEA of Hallmark pathways on a tumour-vs-normal log2 fold-change ranking, shown as a forest plot
* GSEA of a custom signature set against genes ranked by their differential-expression statistic

</details>

### Input columns

<details>

<summary><code>input columns</code></summary>

| column      | type        | required | description                                                                                                                                                      |
| ----------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| value       | numeric     | required | ssGSEA: numeric expression (e.g. TPM, log-norm count, intensity) used to rank genes within each sample. gsea (preranked): the signed per-gene ranking metric su… |
| x\_group    | categorical | required | Gene name (or other feature label) to be matched against the `members` field of each `gene_sets[i]`. Collapsed into the signature label in the output.           |
| patient\_id | any         | required | Patient identifier. Always required. ssGSEA: used for paired statistical tests. gsea (preranked): not used by the scoring itself — supply a single constant (e.… |

</details>

### Visualizations

* `forest` How to read: One row per gene set: the point is the enrichment score (NES by default) and the reference line is 0 — points right of it are enriched at the top of the ranking, points left of it at the bottom. Hover gives the gene-set size, the leading-edge gene count and the p-values; significance lives in the accompanying statistical table.

### Example analysis 1

#### Name — Preranked GSEA of Signatures in TCGA Bladder Patients

#### Analysis parameters

<details>

<summary><code>analysis_name, analysis_params, viz_params</code></summary>

```json
{
  "analysis_name": "enrichment_analysis",
  "analysis_params": {
    "method": "gsea",
    "gene_sets": [
      {
        "members": [
          "CD8A",
          "GZMB",
          "PRF1",
          "GZMA",
          "NKG7"
        ],
        "label": "Cytotoxic"
      },
      {
        "members": [
          "ERBB2",
          "ROR1"
        ],
        "label": "ERBB2_ROR1"
      }
    ],
    "n_perms": 100,
    "score": "nes"
  },
  "viz_params": {
    "plot_name": "forest",
    "value_label": "NES",
    "x_group_label": "Gene set",
    "title": "Preranked GSEA of Signatures in TCGA Bladder Patients"
  }
}
```

</details>

#### Visualization — `forest`

![Preranked GSEA of Signatures in TCGA Bladder Patients](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-6cb01052c4807fd5f28c4bdd7418937d278e8774%2Fenrichment_analysis__gsea__forest.png?alt=media)

#### Output table

<details>

<summary><code>descriptive_stats</code> (2 rows)</summary>

| x\_group    | value  | pval    | fdr     | leading\_edge            | gene\_pct | tag\_pct | n\_leading\_edge | gene\_set\_size | n\_matched |
| ----------- | ------ | ------- | ------- | ------------------------ | --------- | -------- | ---------------- | --------------- | ---------- |
| ERBB2\_ROR1 | 1.328  | 0.04167 | 0.06173 | ERBB2                    | 2.94      | 50.0     | 1                | 2               | 2          |
| Cytotoxic   | -1.112 | 0.3     | 0.2895  | CD8A;PRF1;GZMA;GZMB;NKG7 | 50.98     | 100.0    | 5                | 5               | 5          |

</details>

<details>

<summary><code>statistical_tests</code> (2 rows)</summary>

| x\_group    | pval    | fdr     |
| ----------- | ------- | ------- |
| ERBB2\_ROR1 | 0.04167 | 0.06173 |
| Cytotoxic   | 0.3     | 0.2895  |

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.owkin.com/explore-and-analyse-data/data-analysis/expression-molecular-profiles/pathway-signature-enrichment.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
