> 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/embeddings-scatter-plots.md).

# Embeddings & scatter plots

Position observations by two numeric coordinates and encode a third dimension — metadata, an expression level, or a signature score — in the points' appearance; or assess the agreement of two parallel

Position observations by two numeric coordinates and encode a third dimension — metadata, an expression level, or a signature score — in the points' appearance; or assess the agreement of two parallel measurements of the same observations.

## Embedding coloured by categorical metadata

### Description

#### Analysis summary

Places each cell or sample at its 2-D embedding coordinates and colours the points by a categorical metadata column, quantifying per category how cleanly it separates from the rest of the space.

#### Computation

Each observation is drawn at its (first, second) embedding coordinates. Two geometry statistics are computed per category, in the embedding space itself: the silhouette coefficient — how close each point sits to its own category versus the nearest other one, in \[-1, 1], higher meaning better-separated globally — and the nearest-neighbour purity — the share of each point's 15 nearest neighbours sharing its label, higher meaning more locally homogeneous. Silhouette is estimated on a deterministic stratified subsample (capped at 5000 points; the per-category row reports how many points were actually used); nearest-neighbour purity uses all points. Both are NaN when fewer than two categories are present. No statistical tests are computed.

#### When to use

Use to check how categories occupy an embedding — whether cell types form separate regions, or a condition splits the space. The geometry stats tell you whether the visual separation is real or an artefact of the projection: embeddings do not conserve original distances, so treat the statistics as descriptive of the embedding, not of the underlying data.

#### Caveats

Both metrics are computed in the 2-D embedding, which distorts original distances; a low silhouette may reflect the projection, not the biology. Rare categories with few points give unstable metrics.

### Example questions

<details>

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

* Bulk RNA-seq UMAP colored by metadata variable
* Single-cell UMAP colored by a metadata variable (e.g. cell type, indication, cohort)
* Proteomics UMAP colored by metadata variable

</details>

### Input columns

<details>

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

| column      | type        | required | description                                                                                                                               |
| ----------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| index       | any         | required | Sample/cell identifier (hover, dedup key). Required in every mode.                                                                        |
| x\_value    | numeric     | required | X coordinate. MODE 1/2/3: embedding coord (e.g. umap\_1). MODE 4: x-axis measurement (e.g. bulk log2(TPM+1)).                             |
| y\_value    | numeric     | required | Y coordinate. MODE 1/2/3: embedding coord (e.g. umap\_2). MODE 4: y-axis measurement (e.g. % cells expressing).                           |
| x\_group    | categorical | required | Categorical column. MODE 1: the metadata each point's appearance encodes. MODE 3: gene names to aggregate via the `signatures` parameter. |
| patient\_id | categorical | required | Patient identifier required for population summary statistics.                                                                            |

</details>

### Visualizations

* `scatter` How to read: One dot per observation at its embedding coordinates, coloured by the category it belongs to (legend). Categories whose dots occupy distinct regions separate well; interleaved dots indicate overlap. The accompanying geometry table gives each category its silhouette (global separation, \[-1, 1]) and nearest-neighbour purity (local homogeneity, \[0, 1]) — higher in both means a cleaner separation.

### Example analysis 1

#### Name — UMAP of TCGA Bladder Patients with Clinical T Stage > 2 by Gender

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "scatter_analysis",
  "analysis_params": {
    "mode": "layout_categorical"
  },
  "viz_params": {
    "x_value_label": "UMAP 1",
    "y_value_label": "UMAP 2",
    "color_label": "Gender",
    "index_label": "Sample",
    "plot_name": "scatter",
    "title": "UMAP of TCGA Bladder Patients with Clinical T Stage > 2 by Gender"
  }
}
```

</details>

#### Visualization — `scatter`

![UMAP of TCGA Bladder Patients with Clinical T Stage > 2 by Gender](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-dec1c71960da9e2828f8a9340898fa42a59e007b%2Fscatter_analysis__layout_categorical__scatter.png?alt=media)

#### Output table

<details>

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

| category | n   | silhouette\_category\_mean | nn\_purity\_category\_mean | silhouette\_global\_mean | silhouette\_n\_samples | nn\_purity\_global\_mean |
| -------- | --- | -------------------------- | -------------------------- | ------------------------ | ---------------------- | ------------------------ |
| female   | 65  | 0.002531                   | 0.2985                     | -0.001413                | 223                    | 0.5928                   |
| male     | 158 | -0.003035                  | 0.7139                     | -0.001413                | 223                    | 0.5928                   |

</details>

## Embedding coloured by single-gene expression

### Description

#### Analysis summary

Places each cell or sample at its 2-D embedding coordinates and colours the points by a single gene's expression level, showing where on the embedding the gene is active.

#### Computation

Each observation is drawn at its (first, second) embedding coordinates; the scale encoding its expression value spans the observed range. The gene enters the query as a row filter, not a grouping variable. The value column can be transformed first (log2(value + 1) by request). The descriptive stats table carries the expression distribution summary (expressed fraction, mean among expressing observations, and quantiles). No statistical tests are computed.

#### When to use

Use to localise a single gene's expression on an embedding — which regions of the space (and thus which cell populations) the gene marks. Never pass more than one gene's rows: for several genes use one analysis per gene, and for gene panels use the signature mode of this analysis.

#### Caveats

Encoding only the level overstates low-level expression on sparse counts — observations with a zero read are typically indistinguishable from unexpressed ones; the expressed fraction in the stats table disambiguates.

### Example questions

<details>

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

* Bulk RNA-seq UMAP colored by gene expression
* Single-cell UMAP colored by gene expression
* Proteomics UMAP colored by protein expression

</details>

### Input columns

<details>

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

| column      | type        | required | description                                                                                                                                                       |
| ----------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| index       | any         | required | Sample/cell identifier (hover, dedup key). Required in every mode.                                                                                                |
| x\_value    | numeric     | required | X coordinate. MODE 1/2/3: embedding coord (e.g. umap\_1). MODE 4: x-axis measurement (e.g. bulk log2(TPM+1)).                                                     |
| y\_value    | numeric     | required | Y coordinate. MODE 1/2/3: embedding coord (e.g. umap\_2). MODE 4: y-axis measurement (e.g. % cells expressing).                                                   |
| value       | numeric     | required | Numeric measurement encoded in each point's appearance. MODE 2: one gene's expression (e.g. count\_lognorm). MODE 3: per-gene expression aggregated into signatu… |
| patient\_id | categorical | required | Patient identifier required for population summary statistics.                                                                                                    |

</details>

### Visualizations

* `scatter` How to read: One dot per observation at its embedding coordinates, coloured by the gene's expression level on a continuous colour bar: bright colour marks expressing cells, muted/grey dots mark zero or near-zero values. Regions of coherent colour show where the gene is active. Hovering a dot shows the observation and its value.

### Example analysis 1

#### Name — CD8A Expression in TCGA Bladder Patients (Age > 40)

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "scatter_analysis",
  "analysis_params": {
    "mode": "layout_numeric",
    "mapping": "log2p1"
  },
  "viz_params": {
    "x_value_label": "UMAP 1",
    "y_value_label": "UMAP 2",
    "color_label": "CD8A Expression (log2(TPM+1))",
    "index_label": "Sample",
    "plot_name": "scatter",
    "title": "CD8A Expression in TCGA Bladder Patients (Age > 40)"
  }
}
```

</details>

#### Visualization — `scatter`

![CD8A Expression 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-741cbb84de7dfdcd3a2d5e45db40b09b177f12b6%2Fscatter_analysis__layout_numeric__scatter.png?alt=media)

#### Output table

<details>

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

| n   | n\_zeros | mean\_all | mean\_non\_zero | std\_non\_zero | p50\_non\_zero | max\_non\_zero |
| --- | -------- | --------- | --------------- | -------------- | -------------- | -------------- |
| 431 | 0        | 2.132     | 2.132           | 1.467          | 1.905          | 7.123          |

</details>

## Embedding coloured by gene signature score

### Description

#### Analysis summary

Places each cell or sample at its 2-D embedding coordinates and colours the points by the mean expression of a named gene set (signature), showing where a multi-gene programme is active.

#### Computation

Each observation's expression values for the signature's member genes are averaged into one score per point, which colours the point on the embedding. The descriptive stats table carries the signature-score distribution summary. No statistical tests are computed.

#### When to use

Use to visualise the spatial distribution of a multi-gene programme (e.g. a cytotoxic T-cell signature) across the embedding. Never use this mode with a single gene — use the single-gene mode of this analysis; the two are mutually exclusive.

#### Caveats

A signature score is a plain mean of member genes, not a tested signature: genes with high baseline levels dominate the score, and the score's scale depends on the panel chosen.

### Input columns

<details>

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

| column      | type        | required | description                                                                                                                                                       |
| ----------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| index       | any         | required | Sample/cell identifier (hover, dedup key). Required in every mode.                                                                                                |
| x\_value    | numeric     | required | X coordinate. MODE 1/2/3: embedding coord (e.g. umap\_1). MODE 4: x-axis measurement (e.g. bulk log2(TPM+1)).                                                     |
| y\_value    | numeric     | required | Y coordinate. MODE 1/2/3: embedding coord (e.g. umap\_2). MODE 4: y-axis measurement (e.g. % cells expressing).                                                   |
| value       | numeric     | required | Numeric measurement encoded in each point's appearance. MODE 2: one gene's expression (e.g. count\_lognorm). MODE 3: per-gene expression aggregated into signatu… |
| x\_group    | categorical | required | Categorical column. MODE 1: the metadata each point's appearance encodes. MODE 3: gene names to aggregate via the `signatures` parameter.                         |
| patient\_id | categorical | required | Patient identifier required for population summary statistics.                                                                                                    |

</details>

### Visualizations

* `scatter` How to read: One dot per observation at its embedding coordinates, coloured by the signature's mean score on a continuous colour bar: bright colour marks cells where the programme is active, muted/grey dots where it is silent. Hovering a dot shows the observation and its score.

### Example analysis 1

#### Name — Cytotoxic T-cell Signature UMAP of Single Cell RNA-seq for Mesothelioma

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "scatter_analysis",
  "analysis_params": {
    "mode": "layout_numeric_aggregated",
    "mapping": null,
    "signatures": [
      {
        "members": [
          "CD8A",
          "GZMB"
        ],
        "label": "Cytotoxic T-cell"
      }
    ]
  },
  "viz_params": {
    "x_value_label": "UMAP 1",
    "y_value_label": "UMAP 2",
    "color_label": "Cytotoxic T-cell signature (log-norm)",
    "index_label": "Cell",
    "plot_name": "scatter",
    "title": "Cytotoxic T-cell Signature UMAP of Single Cell RNA-seq for Mesothelioma"
  }
}
```

</details>

#### Visualization — `scatter`

![Cytotoxic T-cell Signature UMAP of Single Cell RNA-seq for Mesothelioma](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-e0a6da3e51193dd79e41f4211cecff4ad09ef3a4%2Fscatter_analysis__layout_numeric_aggregated__scatter.png?alt=media)

#### Output table

<details>

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

| x\_group         | n     | n\_zeros | mean\_all | mean\_non\_zero | std\_non\_zero | p50\_non\_zero | max\_non\_zero |
| ---------------- | ----- | -------- | --------- | --------------- | -------------- | -------------- | -------------- |
| Cytotoxic T-cell | 72988 | 68611    | 0.2376    | 3.962           | 1.336          | 3.72           | 8.937          |

</details>

## Concordance of two parallel measurements

### Description

#### Analysis summary

Compares two parallel measurements of the same observations to assess their agreement, with an overall correlation coefficient.

#### Computation

The two measurements — x and y, observation-aligned — are compared directly. One overall correlation coefficient is computed over the observations where both values are present: Pearson by default, Spearman when requested, reported with its two-sided p-value and the number of contributing pairs (fewer than three pairs yield no coefficient). The descriptive stats table carries the overall mean of each measurement and, when a categorical grouping is provided, one additional row per group with its own means.

#### When to use

Use to assess agreement between two assays or two computational pipelines measuring the same quantity on the same cohort (e.g. bulk RNA-seq expression versus single-cell-derived expression of a gene). For pairwise correlation matrices between many features, use the correlation analyses instead.

#### Caveats

One overall coefficient only — it says nothing about group-specific agreement, and a high correlation does not imply identical scales: a systematic offset between the two measurements is invisible to it.

### Example questions

<details>

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

* Bulk RNA-seq vs single-cell expression concordance for a gene
* Bulk RNA-seq vs spatial transcriptomics expression concordance for a gene
* Bulk RNA-seq vs proteomics intensity concordance for a gene

</details>

### Input columns

<details>

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

| column      | type        | required | description                                                                                                         |
| ----------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| index       | any         | required | Sample/cell identifier (hover, dedup key). Required in every mode.                                                  |
| x\_value    | numeric     | required | X coordinate. MODE 1/2/3: embedding coord (e.g. umap\_1). MODE 4: x-axis measurement (e.g. bulk log2(TPM+1)).       |
| y\_value    | numeric     | required | Y coordinate. MODE 1/2/3: embedding coord (e.g. umap\_2). MODE 4: y-axis measurement (e.g. % cells expressing).     |
| x\_group    | categorical | optional | Categorical column. MODE 4: optional grouping of the observations, adding per-group means to the descriptive stats. |
| patient\_id | categorical | required | Patient identifier required for population summary statistics.                                                      |

</details>

### Visualizations

* `scatter` How to read: One dot per observation at (measurement x, measurement y); the dashed line is the least-squares fit through all points. Dots close to the line agree between the two measurements; systematic departures above or below it signal a scale or offset difference. Points are coloured by the optional grouping column when one is given. The accompanying statistical table reports the overall correlation coefficient with its p-value and the number of contributing pairs.

### Example analysis 1

#### Name — CD8A Bulk vs Single-cell Concordance (Malignant) — MOSAIC Mesothelioma

#### Analysis parameters

<details>

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

```json
{
  "analysis_name": "scatter_analysis",
  "analysis_params": {
    "mode": "concordance",
    "compute_correlation": "pearson"
  },
  "viz_params": {
    "x_value_label": "CD8A Bulk Expression (log2(TPM+1))",
    "y_value_label": "CD8A % Malignant Cells Expressing",
    "color_label": "Gender",
    "index_label": "Sample",
    "plot_name": "scatter",
    "title": "CD8A Bulk vs Single-cell Concordance (Malignant) \u2014 MOSAIC Mesothelioma"
  }
}
```

</details>

#### Visualization — `scatter`

![CD8A Bulk vs Single-cell Concordance (Malignant) — MOSAIC Mesothelioma](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-06480951c9a031de6a81f2459cd77c7b33fa93ca%2Fscatter_analysis__concordance__scatter.png?alt=media)

#### Output table

<details>

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

| group   | n | x\_value\_mean | y\_value\_mean |
| ------- | - | -------------- | -------------- |
| overall | 9 | 3.257          | 1.495          |
| female  | 2 | 2.307          | 1.664          |
| male    | 7 | 3.528          | 1.446          |

</details>

<details>

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

| method  | r      | p\_value | n |
| ------- | ------ | -------- | - |
| pearson | 0.4646 | 0.2077   | 9 |

</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/embeddings-scatter-plots.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.
