> 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/expression-distribution-aggregation.md).

# Expression distribution & aggregation

Compare measurement distributions, categorical compositions, and group averages across samples or patient groups, and explore feature panels with annotated, clustered heatmaps.

Compare measurement distributions, categorical compositions, and group averages across samples or patient groups, and explore feature panels with annotated, clustered heatmaps.

## Distribution (per-sample rows)

### Description

#### Analysis summary

Shows the full distribution of a measurement across patient or sample groups with no averaging: every observation stays its own row, whether the quantity is continuous or categorical.

#### Computation

Every observation is kept as its own row, so nothing is averaged: the measurement is compared between groups on its raw values. For a categorical quantity, the values themselves are the categories each group breaks down into. Pairwise statistical comparisons of the measurement between groups (within each stratum when the data is stratified) are computed automatically and returned with the results.

#### When to use

Use for 'is X different between the groups' questions on raw measurements: gene expression, signature scores, clinical numerics, or the breakdown of a categorical variable across cohorts. When the quantity only exists already aggregated — a mean value per group rather than one row per observation — use this analysis's group-means mode instead.

#### Caveats

Groups with few observations give unstable distribution shapes and noisy comparisons.

### Example questions

<details>

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

* Single gene bulk expression distribution across groups
* Gene bulk expression distribution across multiple genes
* Single gene bulk expression distribution grouped and stratified
* Gene bulk expression distribution across multiple gene signatures
* Single gene signature bulk expression across groups
* Clinical variable distribution across groups

</details>

### Input columns

<details>

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

| column          | type                 | required | description                                                                                                                                                        |
| --------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| index           | any                  | required | Sample/cell/patient identifier — one row per observation when mapping is None, otherwise averaged per group (aggregation).                                         |
| value           | numeric, categorical | required | Measured quantity — continuous or categorical.                                                                                                                     |
| x\_group        | categorical          | required | Grouping variable (e.g. gene name, condition). When using signatures, x\_group must contain the individual gene names to be aggregated into signatures.            |
| y\_group        | categorical          | optional | When signatures is None: the grouping/stratification variable shown on top of x\_group (color/legend). THIS is where a plain 'stratified by X' / 'grouped by X' …  |
| stratify\_group | categorical          | optional | Secondary color/legend stratifier, reserved for the signature case: use ONLY together with signatures + y\_group — y\_group becomes the x-axis after signatures c… |
| patient\_id     | any                  | required | Patient ID for paired statistical tests.                                                                                                                           |

</details>

### Visualizations

* `violin` How to read: Each violin is one group: its width shows where that group's observations concentrate, the embedded box marks the median and the interquartile range of the values, and the dots are the individual observations. Wider sections mean more observations at that value. When the data is stratified, side-by-side violins are keyed by the legend. 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). The y-axis is the measured quantity.
* `boxplot` How to read: Each box shows the distribution of one group's observations: the centre line is the median, the box spans the interquartile range of the values, and the dots are the individual observations — their vertical spread is the observation-to-observation variability within the group. When the data is stratified, side-by-side boxes are keyed by the legend. 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). The y-axis is the measured quantity.
* `bar` How to read: Each bar is one group; its stacked segments (keyed by the legend) show the share of that group's observations falling in each category, summing to 100%, with the percentage written inside each segment. Percentages alone hide the group sizes — hovering a segment shows the underlying counts. Comparing bar heights and segment sizes across groups shows how the category breakdown differs between cohorts. The accompanying statistical table reports the pairwise comparisons between groups.

### Example analysis 1

#### Name — Bulk Expression Distribution of CD8A in TCGA Bladder Patients (Age > 40) by Gender

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "aggregation_analysis",
  "analysis_params": {
    "aggregation_type": null,
    "mapping": "log2p1"
  },
  "viz_params": {
    "index_label": "Sample",
    "x_group_label": "Gender",
    "value_label": "CD8A Expression (log2(TPM+1))",
    "plot_name": "violin",
    "title": "Bulk Expression Distribution of CD8A in TCGA Bladder Patients (Age > 40) by Gender"
  }
}
```

</details>

#### Visualization — `violin`

![Bulk Expression Distribution of CD8A in TCGA Bladder Patients (Age > 40) by Gender](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-7458fb60ebad877c18e3f714a6f7fe7329bca553%2Faggregation_analysis__distribution__violin.png?alt=media)

#### Output table

<details>

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

| x\_group | n   | mean  | std   | min     | p10    | p25    | p50   | p75   | p90   | max   |
| -------- | --- | ----- | ----- | ------- | ------ | ------ | ----- | ----- | ----- | ----- |
| female   | 118 | 2.165 | 1.357 | 0.09196 | 0.4078 | 1.095  | 2.045 | 3.089 | 4.097 | 6.089 |
| male     | 313 | 2.119 | 1.508 | 0.0532  | 0.4843 | 0.8423 | 1.82  | 3.083 | 4.34  | 7.123 |

</details>

<details>

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

| Test used for pairwise comparison | Contrast       | Statistic | Mean Difference | Higher Group | P-value | Adjusted P-value | Significance level | comparison\_a | comparison\_b |
| --------------------------------- | -------------- | --------- | --------------- | ------------ | ------- | ---------------- | ------------------ | ------------- | ------------- |
| wilcoxon                          | (Female, Male) | 19330.0   | 0.04623         | Female       | 0.4534  | 0.4534           |                    | female        | male          |

</details>

### Example analysis 2

#### Name — Bulk Expression Boxplot of CD8A in TCGA Bladder Patients (Age > 40) by Gender

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "aggregation_analysis",
  "analysis_params": {
    "aggregation_type": null,
    "mapping": "log2p1"
  },
  "viz_params": {
    "index_label": "Sample",
    "x_group_label": "Gender",
    "value_label": "CD8A Expression (log2(TPM+1))",
    "plot_name": "boxplot",
    "title": "Bulk Expression Boxplot of CD8A in TCGA Bladder Patients (Age > 40) by Gender"
  }
}
```

</details>

#### Visualization — `boxplot`

![Bulk Expression Boxplot of CD8A in TCGA Bladder Patients (Age > 40) by Gender](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-2177bd0f553eccf018f9c3cd5002aef6d263f5fa%2Faggregation_analysis__distribution__boxplot.png?alt=media)

#### Output table

<details>

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

| x\_group | n   | mean  | std   | min     | p10    | p25    | p50   | p75   | p90   | max   |
| -------- | --- | ----- | ----- | ------- | ------ | ------ | ----- | ----- | ----- | ----- |
| female   | 118 | 2.165 | 1.357 | 0.09196 | 0.4078 | 1.095  | 2.045 | 3.089 | 4.097 | 6.089 |
| male     | 313 | 2.119 | 1.508 | 0.0532  | 0.4843 | 0.8423 | 1.82  | 3.083 | 4.34  | 7.123 |

</details>

<details>

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

| Test used for pairwise comparison | Contrast       | Statistic | Mean Difference | Higher Group | P-value | Adjusted P-value | Significance level | comparison\_a | comparison\_b |
| --------------------------------- | -------------- | --------- | --------------- | ------------ | ------- | ---------------- | ------------------ | ------------- | ------------- |
| wilcoxon                          | (Female, Male) | 19330.0   | 0.04623         | Female       | 0.4534  | 0.4534           |                    | female        | male          |

</details>

### Example analysis 3

#### Name — T Stage Distribution by Cancer Type

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "aggregation_analysis",
  "analysis_params": {
    "aggregation_type": null,
    "mapping": null
  },
  "viz_params": {
    "index_label": "Patient",
    "x_group_label": "Cancer Type",
    "value_label": "T Stage",
    "plot_name": "bar",
    "title": "T Stage Distribution by Cancer Type"
  }
}
```

</details>

#### Visualization — `bar`

![T Stage Distribution by Cancer Type](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-7ee53160a40f2ddaeaceb8f6db8a0cea0a734b57%2Faggregation_analysis__distribution__bar.png?alt=media)

#### Output table

<details>

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

| x\_group                                  | t1  | t2  | t3  | t4 |
| ----------------------------------------- | --- | --- | --- | -- |
| malignant\_neoplasm\_of\_urinary\_bladder | 11  | 191 | 161 | 45 |
| lung\_adenocarcinoma                      | 170 | 278 | 47  | 19 |

</details>

<details>

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

| Test used for pairwise comparison | Contrast     | Statistic | Cramér's V | P-value   | Adjusted P-value | Significance level | comparison\_a        | comparison\_b                             |
| --------------------------------- | ------------ | --------- | ---------- | --------- | ---------------- | ------------------ | -------------------- | ----------------------------------------- |
| chi2                              | (LUAD, BLCA) | 219.6     | 0.488      | 2.485e-47 | 2.485e-47        | ★★★★               | lung\_adenocarcinoma | malignant\_neoplasm\_of\_urinary\_bladder |

</details>

## Group means (raw mean matrix or sample-level distribution)

### Description

#### Analysis summary

Computes the mean of a measurement per group — and per aggregation unit (e.g. sample) when one is given — without z-scoring: the result is one raw mean per group combination, or the full distribution of per-unit means.

#### Computation

The mean of the measurement is computed for every combination of the grouping variables, and per aggregation unit (e.g. sample) when one is given. Without an aggregation unit the result is one raw mean per group combination — e.g. each feature's (gene's, cell type's) mean in each clinical group. With an aggregation unit, one mean is computed per unit and the result keeps the full distribution of those per-unit means, so the unit-to-unit spread stays available rather than being averaged away. Pairwise statistical comparisons of the means between groups (within each stratum when the data is stratified) are computed automatically and returned with the results; when the compared axis is the patient identifier itself — one sample per patient — no comparison runs, as each patient contributes a single value.

#### When to use

Use when raw (un-z-scored) group means are explicitly wanted, or when finer-grained observations should be aggregated up to a coarser unit — for example spatial-transcriptomics spot deconvolution fractions averaged per sample. When features with very different baselines must be compared on a common scale, use this analysis's z-score matrix mode instead; to keep every raw observation visible, use the distribution mode.

#### Caveats

Raw means of features with very different baselines are not directly comparable; and a single mean per group hides the unit-to-unit spread — keep an aggregation unit when that spread matters.

### Example questions

<details>

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

* Spatial deconvolution cell type composition per sample
* Spatial deconvolution cell type composition stratified by clinical variable

</details>

### Input columns

<details>

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

| column          | type                 | required | description                                                                                                                                                              |
| --------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| index           | any                  | required | Sample/cell/patient identifier — one row per observation when mapping is None, otherwise averaged per group (aggregation).                                               |
| value           | numeric, categorical | required | Measured quantity — continuous or categorical.                                                                                                                           |
| x\_group        | categorical          | required | Grouping variable (e.g. gene name, condition). When using signatures, x\_group must contain the individual gene names to be aggregated into signatures.                  |
| y\_group        | categorical          | optional | When signatures is None: the grouping/stratification variable shown on top of x\_group (color/legend). THIS is where a plain 'stratified by X' / 'grouped by X' …        |
| stratify\_group | categorical          | optional | Secondary color/legend stratifier, reserved for the signature case: use ONLY together with signatures + y\_group — y\_group becomes the x-axis after signatures c…       |
| z\_group        | any                  | optional | Aggregation unit (e.g. sample\_id, patient\_id). When present with aggregation\_type='group\_means', one mean per (z\_group, x\_group, \[y\_group]) is computed and its… |
| patient\_id     | any                  | required | Patient ID for paired statistical tests.                                                                                                                                 |

</details>

### Visualizations

* `heatmap` How to read: Each cell shows the raw mean of one feature (row, e.g. a gene) in one group (column): darker/red cells are higher means, blue cells lower ones, on a shared colour scale keyed by the legend. Because the values are raw means rather than z-scores, colour differences between rows reflect each feature's own baseline as much as its group-to-group differences. The accompanying statistical table reports the pairwise comparisons between the columns within each row.
* `boxplot` How to read: Each box shows the distribution of one group's per-unit means (e.g. per-sample averages): the centre line is the median, the box spans the interquartile range, and the dots are the individual aggregation units — their vertical spread is the unit-to-unit variability of the group means. When the data is stratified, side-by-side boxes are keyed by the legend. 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). The y-axis is the mean of the measured quantity.
* `violin` How to read: Each violin is one group: its width shows where that group's per-unit means (e.g. per-sample averages) concentrate, the embedded box marks the median and the middle half, and the dots are the individual aggregation units. Wider sections mean more units with a mean at that value. When the data is stratified, side-by-side violins are keyed by the legend. 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). The y-axis is the mean of the measured quantity.
* `bar` How to read: Each bar is one group; its height is that group's mean of the measured quantity. When the data is stratified, side-by-side bars are keyed by the legend (grouped, not stacked — the means are not shares of a whole). The bar shows the typical value per group but not the unit-to-unit spread — use the boxplot or violin for that. The accompanying statistical table reports the pairwise comparisons between groups.

### Example analysis 1

#### Name — Cell Type Composition by Lymphocyte Density in Tumor (Mosaic Bladder and Ovarian Cancer, Age >40)

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "aggregation_analysis",
  "analysis_params": {
    "aggregation_type": "group_means",
    "mapping": null
  },
  "viz_params": {
    "index_label": "Spot",
    "z_group_label": "Sample",
    "x_group_label": "Cell Type",
    "y_group_label": "Lymphocyte Density in Tumor",
    "value_label": "Mean Deconvolution Fraction",
    "plot_name": "boxplot",
    "title": "Cell Type Composition by Lymphocyte Density in Tumor (Mosaic Bladder and Ovarian Cancer, Age >40)"
  }
}
```

</details>

#### Visualization — `boxplot`

![Cell Type Composition by Lymphocyte Density in Tumor (Mosaic Bladder and Ovarian Cancer, Age >40)](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-2de82be5a9bbcb67491e0b824222eeddeb474e2b%2Faggregation_analysis__group_means__boxplot.png?alt=media)

#### Output table

<details>

<summary><code>descriptive_stats</code> (first 10 of 210 rows)</summary>

| x\_group | y\_group | z\_group          | n    | mean    | std     | min       | p10       | p25       | p50      | p75     | p90     | max    |
| -------- | -------- | ----------------- | ---- | ------- | ------- | --------- | --------- | --------- | -------- | ------- | ------- | ------ |
| b\_cell  | High     | PAT\_B\_099UHY7Aa | 4780 | 0.0224  | 0.08046 | 8.733e-05 | 0.0005729 | 0.001158  | 0.003025 | 0.01008 | 0.03748 | 0.9128 |
| b\_cell  | High     | PAT\_B\_2RWF1S17a | 4328 | 0.01886 | 0.04577 | 8.053e-05 | 0.0002776 | 0.0006445 | 0.002499 | 0.01222 | 0.05024 | 0.4502 |
| b\_cell  | High     | PAT\_B\_IIOB0I9Fa | 3587 | 0.0312  | 0.03786 | 0.0005207 | 0.006134  | 0.01068   | 0.01952  | 0.03652 | 0.06709 | 0.4613 |
| b\_cell  | High     | PAT\_B\_R7AHWHKa  | 4708 | 0.03798 | 0.03159 | 0.002957  | 0.01152   | 0.01753   | 0.02897  | 0.0476  | 0.07541 | 0.3214 |
| b\_cell  | High     | PAT\_B\_XPZVU2VWa | 4239 | 0.01744 | 0.05276 | 0.0002552 | 0.001308  | 0.002403  | 0.005071 | 0.01221 | 0.03559 | 0.9778 |
| b\_cell  | High     | PAT\_B\_Z8O7TMSTa | 4800 | 0.01836 | 0.0679  | 8.681e-05 | 0.0005702 | 0.001192  | 0.003348 | 0.01019 | 0.033   | 0.9886 |
| b\_cell  | High     | PAT\_O\_3V2TK1Z8a | 4455 | 0.01395 | 0.02071 | 0.001781  | 0.003794  | 0.005458  | 0.009034 | 0.01502 | 0.02572 | 0.4943 |
| b\_cell  | High     | PAT\_O\_78Y2ZKXAa | 3838 | 0.01361 | 0.01637 | 0.0009229 | 0.00251   | 0.004555  | 0.008002 | 0.01654 | 0.03108 | 0.337  |
| b\_cell  | Low      | PAT\_B\_6FO1C2RZa | 4469 | 0.01812 | 0.01849 | 0.0002283 | 0.00355   | 0.006391  | 0.01241  | 0.02308 | 0.03901 | 0.1915 |
| b\_cell  | Low      | PAT\_B\_8PA2US70a | 4755 | 0.02314 | 0.01449 | 0.002229  | 0.01193   | 0.01505   | 0.01889  | 0.02628 | 0.03944 | 0.2092 |

</details>

<details>

<summary><code>statistical_tests</code> (first 10 of 33 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                          | T nk        | (High, Low)    | 41.0      | 0.01164         | High         | 0.0293  | 0.5238           |                    | High          | Low           |
| wilcoxon                          | Granulocyte | (Low, Medium)  | 1.0       | -0.02812        | Medium       | 0.03175 | 0.5238           |                    | Low           | Medium        |
| wilcoxon                          | T nk        | (Low, Medium)  | 6.0       | -0.01489        | Medium       | 0.06494 | 0.7143           |                    | Low           | Medium        |
| wilcoxon                          | Fibroblast  | (High, Low)    | 36.0      | 0.08397         | High         | 0.1419  | 0.8447           |                    | High          | Low           |
| wilcoxon                          | Plasma      | (High, Medium) | 12.0      | -0.01497        | Medium       | 0.1419  | 0.8447           |                    | High          | Medium        |
| wilcoxon                          | Momac       | (Low, Medium)  | 9.0       | -0.03164        | Medium       | 0.1797  | 0.8447           |                    | Low           | Medium        |
| wilcoxon                          | Muscle      | (Low, Medium)  | 26.0      | 0.07519         | Low          | 0.2403  | 0.8447           |                    | Low           | Medium        |
| wilcoxon                          | Granulocyte | (High, Medium) | 6.0       | -0.02472        | Medium       | 0.2571  | 0.8447           |                    | High          | Medium        |
| wilcoxon                          | Momac       | (High, Medium) | 16.0      | -0.02447        | Medium       | 0.345   | 0.8447           |                    | High          | Medium        |
| wilcoxon                          | Endothelial | (High, Low)    | 32.0      | 0.003314        | High         | 0.345   | 0.8447           |                    | High          | Low           |

</details>

### Example analysis 2

#### Name — Cell Type Composition (Mosaic Bladder and Ovarian Cancer, Age >40)

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "aggregation_analysis",
  "analysis_params": {
    "aggregation_type": "group_means",
    "mapping": null
  },
  "viz_params": {
    "index_label": "Spot",
    "z_group_label": "Sample",
    "x_group_label": "Cell Type",
    "value_label": "Mean Deconvolution Fraction",
    "plot_name": "violin",
    "title": "Cell Type Composition (Mosaic Bladder and Ovarian Cancer, Age >40)"
  }
}
```

</details>

#### Visualization — `violin`

![Cell Type Composition (Mosaic Bladder and Ovarian Cancer, Age >40)](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-126c9439c10188e1689fd3485d7c56e3fa41359a%2Faggregation_analysis__group_means__violin.png?alt=media)

#### Output table

<details>

<summary><code>descriptive_stats</code> (first 10 of 219 rows)</summary>

| x\_group | z\_group          | n    | mean    | std     | min       | p10       | p25       | p50      | p75     | p90     | max    |
| -------- | ----------------- | ---- | ------- | ------- | --------- | --------- | --------- | -------- | ------- | ------- | ------ |
| b\_cell  | PAT\_B\_099UHY7Aa | 4780 | 0.0224  | 0.08046 | 8.733e-05 | 0.0005729 | 0.001158  | 0.003025 | 0.01008 | 0.03748 | 0.9128 |
| b\_cell  | PAT\_B\_2BM8C3X4a | 4850 | 0.02314 | 0.06097 | 0.0002309 | 0.001404  | 0.002689  | 0.006287 | 0.01653 | 0.04922 | 0.9008 |
| b\_cell  | PAT\_B\_2RWF1S17a | 4328 | 0.01886 | 0.04577 | 8.053e-05 | 0.0002776 | 0.0006445 | 0.002499 | 0.01222 | 0.05024 | 0.4502 |
| b\_cell  | PAT\_B\_5WTQ8UP5a | 4399 | 0.03371 | 0.04651 | 0.0008838 | 0.00737   | 0.01113   | 0.01894  | 0.03591 | 0.07188 | 0.563  |
| b\_cell  | PAT\_B\_6FO1C2RZa | 4469 | 0.01812 | 0.01849 | 0.0002283 | 0.00355   | 0.006391  | 0.01241  | 0.02308 | 0.03901 | 0.1915 |
| b\_cell  | PAT\_B\_8PA2US70a | 4755 | 0.02314 | 0.01449 | 0.002229  | 0.01193   | 0.01505   | 0.01889  | 0.02628 | 0.03944 | 0.2092 |
| b\_cell  | PAT\_B\_BXQ36W6Aa | 4771 | 0.01436 | 0.0294  | 0.0003797 | 0.001884  | 0.003144  | 0.005917 | 0.01292 | 0.02996 | 0.4975 |
| b\_cell  | PAT\_B\_CX5442GKa | 4884 | 0.0241  | 0.02636 | 0.002018  | 0.008132  | 0.01113   | 0.01684  | 0.02758 | 0.04405 | 0.4873 |
| b\_cell  | PAT\_B\_FA0SCL0Da | 4174 | 0.01951 | 0.01977 | 0.0005785 | 0.001715  | 0.004005  | 0.01556  | 0.02878 | 0.04195 | 0.2476 |
| b\_cell  | PAT\_B\_IC1SLIIMa | 4750 | 0.01692 | 0.03003 | 0.0006124 | 0.002434  | 0.003856  | 0.007505 | 0.01691 | 0.03817 | 0.8607 |

</details>

<details>

<summary><code>statistical_tests</code> (first 10 of 55 rows)</summary>

| Test used for pairwise comparison | Contrast                 | Statistic | Mean Difference | Higher Group | P-value   | Adjusted P-value | Significance level | comparison\_a | comparison\_b |
| --------------------------------- | ------------------------ | --------- | --------------- | ------------ | --------- | ---------------- | ------------------ | ------------- | ------------- |
| wilcoxon                          | (Malignant, B cell)      | 439.0     | 0.2611          | Malignant    | 4.159e-08 | 6.703e-07        | ★★★★               | malignant     | b\_cell       |
| wilcoxon                          | (Malignant, Dc)          | 439.0     | 0.2616          | Malignant    | 4.159e-08 | 6.703e-07        | ★★★★               | malignant     | dc            |
| wilcoxon                          | (Momac, Dc)              | 437.0     | 0.06135         | Momac        | 5.522e-08 | 6.703e-07        | ★★★★               | momac         | dc            |
| wilcoxon                          | (B cell, Fibroblast)     | 4.0       | -0.186          | Fibroblast   | 5.522e-08 | 6.703e-07        | ★★★★               | b\_cell       | fibroblast    |
| wilcoxon                          | (Momac, B cell)          | 436.0     | 0.06082         | Momac        | 6.356e-08 | 6.703e-07        | ★★★★               | momac         | b\_cell       |
| wilcoxon                          | (Fibroblast, Dc)         | 435.0     | 0.1865          | Fibroblast   | 7.312e-08 | 6.703e-07        | ★★★★               | fibroblast    | dc            |
| wilcoxon                          | (T nk, Malignant)        | 9.0       | -0.2397         | Malignant    | 1.109e-07 | 8.715e-07        | ★★★★               | t\_nk         | malignant     |
| wilcoxon                          | (Malignant, Plasma)      | 430.0     | 0.2399          | Malignant    | 1.46e-07  | 1.004e-06        | ★★★★               | malignant     | plasma        |
| wilcoxon                          | (Malignant, Endothelial) | 426.0     | 0.2343          | Malignant    | 2.51e-07  | 1.534e-06        | ★★★★               | malignant     | endothelial   |
| wilcoxon                          | (Mast, Malignant)        | 0.0       | -0.2643         | Malignant    | 4.711e-07 | 2.356e-06        | ★★★★               | mast          | malignant     |

</details>

## Z-score matrix (heatmap)

### Description

#### Analysis summary

Computes the mean of a measurement per feature-group combination, then standardises each feature's row so features with very different baselines become comparable — the conventional form for comparing several genes across clinical groups.

#### Computation

Group means are computed as in the raw-means mode, then each feature's row of means is z-scored: the row's mean is subtracted and divided by its standard deviation. Each cell therefore shows how far that group's value sits from the feature's own average across groups, in standard deviations, rather than in the measurement's own units. Pairwise statistical comparisons of the means between the groups within each feature's row are computed automatically and returned with the results; when the grouping axis is the patient identifier itself — one sample per patient — no comparison runs.

#### When to use

Use whenever several features are compared across clinical groups without an explicit preference for raw means: it makes features with different baseline levels comparable on the same scale. Use this — not the clustered-matrix mode — when the request names exactly one stratifying/clinical variable, with no clustering request and no annotation variables. When raw (unstandardised) values are wanted — e.g. a direct group-by-gene mean-expression table — use this analysis's group-means mode instead.

#### Caveats

Z-scores remove absolute levels: a strongly positive cell means 'high for this feature', not 'high in absolute terms', and rows that barely vary across groups get large-looking relative differences. Averaging across aggregation units yields the typical pattern per group but not the unit-to-unit spread.

### Example questions

<details>

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

* Average expression variability of different genes across groups

</details>

### Input columns

<details>

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

| column          | type                 | required | description                                                                                                                                                              |
| --------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| index           | any                  | required | Sample/cell/patient identifier — one row per observation when mapping is None, otherwise averaged per group (aggregation).                                               |
| value           | numeric, categorical | required | Measured quantity — continuous or categorical.                                                                                                                           |
| x\_group        | categorical          | required | Grouping variable (e.g. gene name, condition). When using signatures, x\_group must contain the individual gene names to be aggregated into signatures.                  |
| y\_group        | categorical          | optional | When signatures is None: the grouping/stratification variable shown on top of x\_group (color/legend). THIS is where a plain 'stratified by X' / 'grouped by X' …        |
| stratify\_group | categorical          | optional | Secondary color/legend stratifier, reserved for the signature case: use ONLY together with signatures + y\_group — y\_group becomes the x-axis after signatures c…       |
| z\_group        | any                  | optional | Aggregation unit (e.g. sample\_id, patient\_id). When present with aggregation\_type='group\_means', one mean per (z\_group, x\_group, \[y\_group]) is computed and its… |
| patient\_id     | any                  | required | Patient ID for paired statistical tests.                                                                                                                                 |

</details>

### Visualizations

* `heatmap` How to read: Each cell shows how far one feature's mean in one group sits from that feature's own average across the groups, in standard deviations: red cells are above the feature's average, blue cells below, centred on the mid-point colour. Because each row is standardised separately, comparing colours between rows asks 'where does this group sit relative to the feature's typical level?', not 'which group has the higher absolute value?'. A row whose cells all share one colour barely varies between groups. The accompanying statistical table reports the pairwise comparisons between the columns within each row.

### Example analysis 1

#### Name — Bulk Expression of ERBB2, TP53 and ROR1 by Lymphocyte Density in Tumor (Age > 40)

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "aggregation_analysis",
  "analysis_params": {
    "aggregation_type": "zscore_matrix",
    "mapping": "log2p1"
  },
  "viz_params": {
    "index_label": "Sample",
    "x_group_label": "Lymphocyte Density in Tumor",
    "y_group_label": "Gene",
    "value_label": "Expression (log2(TPM+1))",
    "plot_name": "heatmap",
    "title": "Bulk Expression of ERBB2, TP53 and ROR1 by Lymphocyte Density in Tumor (Age > 40)"
  }
}
```

</details>

#### Visualization — `heatmap`

![Bulk Expression of ERBB2, TP53 and ROR1 by Lymphocyte Density in Tumor (Age > 40)](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-e4368e0d2e265bcfc0260740c288d840cdd737f4%2Faggregation_analysis__zscore_matrix__heatmap.png?alt=media)

#### Output table

<details>

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

| x\_group | y\_group | value\_mean | n   | value\_zscore |
| -------- | -------- | ----------- | --- | ------------- |
| High     | ROR1     | 1.026       | 190 | 0.8087        |
| High     | TP53     | 5.207       | 190 | -0.7136       |
| Low      | ERBB2    | 7.724       | 122 | 0.4515        |
| Low      | TP53     | 5.514       | 122 | 1.143         |
| Medium   | ERBB2    | 7.749       | 119 | 0.6946        |
| Low      | ROR1     | 0.7712      | 122 | -1.118        |
| High     | ERBB2    | 7.557       | 190 | -1.146        |
| Medium   | ROR1     | 0.9604      | 119 | 0.3095        |
| Medium   | TP53     | 5.254       | 119 | -0.4294       |

</details>

<details>

<summary><code>statistical_tests</code> (9 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                          | TP53  | (High, Low)    | 9151.0    | -0.3074         | Low          | 0.001712 | 0.01541          | ★                  | High          | Low           |
| wilcoxon                          | ROR1  | (Low, Medium)  | 6027.0    | -0.1891         | Medium       | 0.02285  | 0.1028           |                    | Low           | Medium        |
| wilcoxon                          | TP53  | (Low, Medium)  | 8295.0    | 0.2603          | Low          | 0.05566  | 0.1334           |                    | Low           | Medium        |
| wilcoxon                          | ROR1  | (High, Low)    | 13060.0   | 0.2552          | High         | 0.05929  | 0.1334           |                    | High          | Low           |
| wilcoxon                          | ERBB2 | (High, Medium) | 10360.0   | -0.1917         | Medium       | 0.216    | 0.328            |                    | High          | Medium        |
| wilcoxon                          | ERBB2 | (High, Low)    | 10630.0   | -0.1664         | Low          | 0.2187   | 0.328            |                    | High          | Low           |
| wilcoxon                          | TP53  | (High, Medium) | 10700.0   | -0.04705        | Medium       | 0.4313   | 0.5545           |                    | High          | Medium        |
| wilcoxon                          | ROR1  | (High, Medium) | 11100.0   | 0.06613         | High         | 0.788    | 0.8865           |                    | High          | Medium        |
| wilcoxon                          | ERBB2 | (Low, Medium)  | 7253.0    | -0.02533        | Medium       | 0.9919   | 0.9919           |                    | Low           | Medium        |

</details>

## Clustered matrix with annotation tracks

### Description

#### Analysis summary

Builds a feature-by-sample matrix (e.g. genes by samples) from per-observation measurements, plus per-sample and per-feature annotation tables carrying additional metadata (e.g. treatment arm, pathway).

#### Computation

Averages the measurement per (feature, sample) combination into a wide matrix — one row per feature, one column per sample — keeping every feature and sample from the query. Per-sample and per-feature annotation tables (one row per sample or feature, one column per annotation variable) are returned alongside the matrix. No automatic statistical tests are computed in this mode.

#### When to use

Reach for this mode when the request wants features and/or samples clustered by similarity and/or two or more annotation variables on named samples. When the request names exactly one stratifying/clinical variable with no clustering and no extra annotation variables, use this analysis's z-score matrix mode instead.

#### Caveats

Clustering is descriptive, not inferential: groupings carry no significance test, and the ordering depends on the clustering settings and the feature panel chosen.

### Example questions

<details>

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

* Clustered heatmap of a gene panel across samples, annotated by treatment arm
* Heatmap of marker genes across samples clustered by both genes and samples
* Gene expression heatmap with a clinical annotation track above and a pathway annotation to the left
* Gene expression heatmap of a panel annotated by a different gene's WES CNV-alteration status and a clinical stage variable

</details>

### Input columns

<details>

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

| column           | type                 | required | description                                                                                                                                                          |
| ---------------- | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| index            | any                  | required | Sample/cell/patient identifier — one row per observation when mapping is None, otherwise averaged per group (aggregation).                                           |
| value            | numeric, categorical | required | Measured quantity — continuous or categorical.                                                                                                                       |
| x\_group         | categorical          | required | Grouping variable (e.g. gene name, condition). When using signatures, x\_group must contain the individual gene names to be aggregated into signatures.              |
| y\_group         | categorical          | optional | When signatures is None: the grouping/stratification variable shown on top of x\_group (color/legend). THIS is where a plain 'stratified by X' / 'grouped by X' …    |
| stratify\_group  | categorical          | optional | Secondary color/legend stratifier, reserved for the signature case: use ONLY together with signatures + y\_group — y\_group becomes the x-axis after signatures c…   |
| patient\_id      | any                  | required | Patient ID for paired statistical tests.                                                                                                                             |
| sample\_anno\_\* | any                  | optional | complex\_heatmap only. Optional per-sample annotation column(s) — one value per sample (e.g. sample\_anno\_treatment\_arm). Value must be constant for every row sh… |
| bottom\_anno\_\* | any                  | optional | complex\_heatmap only. Optional per-sample annotation column(s) — one value per sample (e.g. bottom\_anno\_batch). Value must be constant for every row sharing th…  |
| row\_anno\_\*    | any                  | optional | complex\_heatmap only. Optional per-row annotation column(s) — one value per row id (e.g. row\_anno\_pathway). Value must be constant for every row sharing the sa…  |

</details>

### Visualizations

* `complex_heatmap` How to read: The heatmap's columns are samples and its rows are features (e.g. genes), colored by each feature's standardised level in each sample: red above the feature's average across samples, blue below, with blank cells where no value exists. Dendrograms attach samples and/or features ordered by similarity — branches that join close to the root are the least alike, and columns/rows sitting side by side within a cluster are the most similar. Each color strip above or below the columns (or left of the rows) gives one piece of metadata per sample or feature, keyed by the legend, so cluster patterns can be read against them; hovering a cell or strip shows the sample and its patient. The rows shown are the most variable ones when the panel exceeds the display cap.

### Example analysis 1

#### Name — Immuno-Oncology Gene Panel Across Bladder Patients, Annotated by TP53 CNV-Alteration Status and Gender, with Per-Gene Number of Mutated Samples as a Row Annotation

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "aggregation_analysis",
  "analysis_params": {
    "complex_heatmap": true
  },
  "viz_params": {
    "plot_name": "complex_heatmap",
    "title": "Immuno-Oncology Gene Panel Across Bladder Patients, Annotated by TP53 CNV-Alteration Status and Gender, with Per-Gene Number of Mutated Samples as a Row Annotation"
  }
}
```

</details>

#### Visualization — `complex_heatmap`

![Immuno-Oncology Gene Panel Across Bladder Patients, Annotated by TP53 CNV-Alteration Status and Gender, with Per-Gene Number of Mutated Samples as a Row Annotation](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-cd4fbc1ddcac1e3640286194cb0b880b167a0d6a%2Faggregation_analysis__complex_heatmap__complex_heatmap.png?alt=media)

#### Output table

<details>

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

| index | mean\_value | std\_value | n\_observations | n\_samples |
| ----- | ----------- | ---------- | --------------- | ---------- |
| CD274 | 2.352       | 1.535      | 433             | 433        |
| CD8A  | 2.127       | 1.466      | 433             | 433        |
| ERBB2 | 7.657       | 1.367      | 433             | 433        |
| ROR1  | 0.9441      | 0.9046     | 432             | 432        |

</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/expression-distribution-aggregation.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.
