> For the complete documentation index, see [llms.txt](https://cgps.gitbook.io/data-flo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cgps.gitbook.io/data-flo/reference-guide/add-jittering.md).

# add-jittering

## Description

<mark style="color:purple;">`add-jittering`</mark> *adaptor can be used to add random noise to numeric columns in a datatable, which can be helpful when visualising geographical coordinates on a map.*

Jittering introduces variability to the data points' positions, spreading them out slightly and providing a clearer representation of the density and distribution of points. Further, jittering adds stochasticity to specified numeric columns in a datatable.

## Inputs

**`data`**\
Type: `datatable`\
Required: Yes\
The datatable containing the columns to be jittered.

**`columns`**\
Type: `list`\
Required: Yes\
The names of the columns to which jittering will be added.

**`range`**\
Type: `number`\
Required: No\
The maximum distance from the original value. If unspecified, defaults to `1`.

**`unit`**\
Type: `text`\
Required: No\
The unit of the range value. For jittering geographical coordinates use either `kilometers`, `meters`, `miles`, or `none`. If unspecified, defaults to `none`.

**`digits`**\
Type: `number`\
Required: No\
The number of digits to appear after the decimal point; should be a value between 0 and 100, inclusive. If this argument is omitted, it is treated as 6.

## Outputs

**`data`**\
Type: `datatable`\
A datatable with jittered values in the specified columns.

## Examples

### Example 1: Default behaviour.

#### Inputs:

`data`:

<table><thead><tr><th width="128">id</th><th width="132">latitude</th><th width="139">longitude</th></tr></thead><tbody><tr><td>Sample A</td><td>4.0</td><td>8.0</td></tr><tr><td>Sample B</td><td>5.0</td><td>9.0</td></tr><tr><td>Sample C</td><td>5.0</td><td>9.0</td></tr><tr><td>Sample D</td><td>4.0</td><td>8.0</td></tr></tbody></table>

`columns`:

1. latitude
2. longitude

`unit`: kilometers

#### Outputs:

`data`:

<table><thead><tr><th width="128">id</th><th width="132">latitude</th><th width="139">longitude</th></tr></thead><tbody><tr><td>Sample A</td><td>3.997208</td><td>8.000714</td></tr><tr><td>Sample B</td><td>5.002011</td><td>9.001153</td></tr><tr><td>Sample C</td><td>4.996007</td><td>9.00033</td></tr><tr><td>Sample D</td><td>4.001309</td><td>7.994139</td></tr></tbody></table>

-> In this example, we jitter geographical coordinates, by moving them up to one kilometer, so they do not stack on top of each other when plotting them on a map.

### Example 2: Jitter patient ages.

#### Inputs:

`data`:

<table><thead><tr><th width="127.60000000000002">Name</th><th width="74">Age</th></tr></thead><tbody><tr><td>Patient A</td><td>20</td></tr><tr><td>Patient B</td><td>60</td></tr><tr><td>Patient C</td><td>32</td></tr></tbody></table>

`columns`:

1. Age

`range`: 10

`digits`: 0

#### Outputs:

`data`:

<table><thead><tr><th width="128.8193832599119">Name</th><th width="100">Age</th></tr></thead><tbody><tr><td>Patient A</td><td>28</td></tr><tr><td>Patient B</td><td>55</td></tr><tr><td>Patient C</td><td>33</td></tr></tbody></table>

-> In this example, we jitter patient ages randomly to help anonymise information, by adding or subtracting random values between 0 and 10 (the value specified in `range`), we set `digits` to `0` to return whole numbers (integers).

### Use Cases

* Scatter plots: Applying jittering to the data points, makes it easier to see the density and distribution of points in areas with high overlap.
* Categorical data: Jittering adds variability to the position of data points, making it easier to distinguish categories with high densities of data. Without jittering, dense clusters of points might create the impression of a single point or a smaller number of points.
* Data with small sample size: In cases where the sample size is small and data points are concentrated around a few values, jittering can be useful to prevent points from directly overlapping and to give a better sense of the underlying distribution.

Note: It's important to note that jittering introduces a degree of artificiality to the visualisation and should be noted for users interpreting these visualisations.