> 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/general-purpose/correlation-matrix.md).

# Correlation matrix

Measure pairwise associations between genes, proteins, or signatures using Pearson or Spearman correlation, summarized in a correlation matrix.

Measure pairwise associations between genes, proteins, or signatures using Pearson or Spearman correlation, summarized in a correlation matrix.

## Pairwise correlation matrix

### Description

#### Analysis summary

Measures how strongly pairs of features — genes, proteins, signatures — move together across a cohort: every pair's correlation coefficient is computed over the per-sample values, yielding a symmetric coefficient matrix.

#### Computation

Values are log-transformed by default, then every pair of features is correlated across samples: Pearson's r by default, or Spearman's rank correlation when the relationship may be monotonic but not linear. The result is a symmetric matrix of coefficients ranging from −1 (perfect negative association) through 0 (no association) to +1 (perfect positive), with 1 on the diagonal. Each pair also carries a two-sided p-value for the correlation being zero, returned with the results.

#### When to use

Use when the user asks for correlation coefficients or a pairwise correlation matrix between named features. For binary co-occurrence — Jaccard-index overlap or the percentage of cells co-expressing two markers — use coexpression\_analysis instead.

#### Caveats

Correlation captures linear (Pearson) or monotonic (Spearman) association, not causation, and a handful of samples can make it unstable. Each pair's p-value is uncorrected for the many pairs tested, so large panels produce small p-values by chance. Samples missing any feature's value are dropped before correlating, so the effective cohort is the intersection across the whole panel.

### Example questions

<details>

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

* Pairwise correlation of multiple gene bulk expression

</details>

### Input columns

<details>

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

| column      | type        | required | description                                                            |
| ----------- | ----------- | -------- | ---------------------------------------------------------------------- |
| index       | any         | required | Sample/cell/patient identifier — used to align entity vectors.         |
| value       | numeric     | required | Measured quantity to correlate across entities.                        |
| x\_group    | categorical | required | Entity name (e.g. gene, protein) — each unique value becomes one axis. |
| patient\_id | categorical | required | Patient identifier required for population summary statistics.         |

</details>

### Visualizations

* `heatmap` How to read: Each cell colours the correlation between one feature (row) and another (column): red means they rise and fall together, blue means one tends to fall as the other rises, and the neutral middle colour means no association — on a fixed scale from -1 to +1. The matrix is symmetric (a cell and its mirror are the same pair) and the diagonal is always 1. A row of strong colour marks a feature that co-varies with many others. Hovering a cell shows the exact coefficient; the accompanying table adds each pair's p-value. Colour measures association, not level: two strongly red features can sit at very different absolute values.

### Example analysis 1

#### Name — Pearson Correlation between ERBB2 and TP53 in TCGA Bladder Patients (Age > 40)

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "correlation_analysis",
  "analysis_params": {
    "mapping": "log2p1",
    "correlation_method": "pearson"
  },
  "viz_params": {
    "index_label": "Sample",
    "x_group_label": "Gene",
    "plot_name": "heatmap",
    "title": "Pearson Correlation between ERBB2 and TP53 in TCGA Bladder Patients (Age > 40)"
  }
}
```

</details>

#### Visualization — `heatmap`

![Pearson Correlation between ERBB2 and TP53 in TCGA Bladder Patients (Age > 40)](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-b8eb11e24f3488c10cd4934d309f4d713151b04b%2Fcorrelation_analysis__correlation_matrix__heatmap.png?alt=media)

#### Output table

<details>

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

| x\_group\_a | x\_group\_b | correlation | p\_value | test   |
| ----------- | ----------- | ----------- | -------- | ------ |
| ERBB2       | TP53        | 0.1079      | 0.02513  | t-test |

</details>

<details>

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

| x\_group\_a | x\_group\_b | correlation | p\_value | test   |
| ----------- | ----------- | ----------- | -------- | ------ |
| ERBB2       | TP53        | 0.1079      | 0.02513  | t-test |

</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/general-purpose/correlation-matrix.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.
