# 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.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cgps.gitbook.io/data-flo/reference-guide/add-jittering.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.