# Relative Change Alerts

Canonical page: https://www.adaptabletools.com/docs/handbook-alerting-relative-change

- Relative Change Alerts evaluate based on the nature of the data change in a Cell’s value
- They can respond to any change, a relative change or an absolute change

Relative Change Alerts are similar to [Data Change Alerts](https://www.adaptabletools.com/docs/handbook-alerting-data-change/index.md), but they evaluate on the **relative nature** of the change made to a given Cell's value.

In the Alert Wizard they are a first-class **Alert Type** (`Type: 'RelativeChange'`). The Rule step uses the Expression Editor (no Query Builder) with toolbar chips for `ANY_CHANGE`, `PERCENT_CHANGE` and `ABSOLUTE_CHANGE`. Column Scope is configured on the Trigger step, the same as Data Change Alerts.

There are 3 Relative Change Expression Functions:

| Function        | When Alert is Triggered                                     |
| --------------- | ----------------------------------------------------------- |
| ANY_CHANGE      | **Any** change at all to the Cell's value                   |
| PERCENT_CHANGE  | If the value of Cell changes by a given **percent** amount  |
| ABSOLUTE_CHANGE | If the value of Cell changes by a given **absolute** amount |

See [Relative Change Expressions in AdapTableQL](https://www.adaptabletools.com/docs/adaptable-ql-expression-relative-change/index.md) for more details

## Any Change

Any *Any Change* Alert fires if there is **any** change at all to the Cell's value.

It leverages the `ANY_CHANGE` [Expression Function](https://www.adaptabletools.com/docs/adaptable-ql-expression-relative-change/index.md).

**Example: Alerts: Relative Any Change**

Alerts fired due to Any Change

- This example displays an *Info* Alert which fires when there is **any change** to a Cell's value in any numeric column (using `ANY_CHANGE` expression)

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Relative Any Change Alert',
  initialState: {
    Dashboard: {
      ModuleButtons: ['Alert'],
      Tabs: [
        {
          Name: 'Toolbars',
          Toolbars: ['Alert'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Alert'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-info-name-change',
          Type: 'RelativeChange',
          MessageType: 'Info',
          Scope: {
            DataTypes: ['number'],
          },
          Rule: 'ANY_CHANGE([name])',
          AlertProperties: {
            DisplayNotification: true,
            HighlightCell: true,
          },
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Percent Change

A *Percent Change* Alert fires if the value of a Cell changes by a given **percent** amount.

It leverages the `PERCENT_CHANGE` [Expression Function](https://www.adaptabletools.com/docs/adaptable-ql-expression-relative-change/index.md).

`PERCENT_CHANGE` can be given a "direction" to limit the evaluation to percent increases or decreases

**Example: Alerts: Relative Percent Change**

Alerts fired due to a Percent Change

- This example displays 2 *Warning* Alerts which check for relative percent changes (leveraging the `PERCENT_CHANGE` expression function)
  - on the `Github Stars` column if the cell's value changes by more than 50% (in any direction)
  - on the `Github Watchers` column if the cell's value **increases** by more than 50%

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Relative Percent Change Alert',
  initialState: {
    Dashboard: {
      ModuleButtons: ['Alert'],
      Tabs: [
        {
          Name: 'Toolbars',
          Toolbars: ['Alert'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Alert'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-warning-github-stars',
          MessageType: 'Warning',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Type: 'RelativeChange',
          Rule: 'PERCENT_CHANGE([github_stars]) > 50',
          AlertProperties: {
            DisplayNotification: true,
            HighlightCell: true,
          },
        },
        {
          Name: 'alert-warning-github-watchers',
          Type: 'RelativeChange',
          MessageType: 'Warning',
          Scope: {
            ColumnIds: ['github_watchers'],
          },
          Rule: 'PERCENT_CHANGE([github_watchers], "INCREASE") > 50',
          AlertProperties: {
            DisplayNotification: true,
            HighlightCell: true,
          },
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'github_watchers',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Absolute Change

An *Absolute Change* Alert fires if the value of a Cell changes by a given **absolute** amount.

It leverages the `ABSOLUTE_CHANGE` [Expression Function](https://www.adaptabletools.com/docs/adaptable-ql-expression-relative-change/index.md).

`ABSOLUTE_CHANGE` can be given a "direction" to limit the evaluation to absolute increases or decreases

**Example: Alerts: Relative Absolute Change**

Alerts fired due to an Absolute Change

- This example displays 2 *Success* Alerts which check for relative absolute changes (leveraging the `ABSOLUTE_CHANGE` expression function)
  - on the `Github Stars` column if the cell's value changes by more than 100 (in any direction)
  - on the `Github Watchers` column if the cell's value **decreases** by exactly 20

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Relative Absolute Change Alert',
  initialState: {
    Dashboard: {
      ModuleButtons: ['Alert'],
      Tabs: [
        {
          Name: 'Toolbars',
          Toolbars: ['Alert'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Alert'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-success-github-stars',
          Type: 'RelativeChange',
          MessageType: 'Success',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Rule: 'ABSOLUTE_CHANGE([github_stars]) > 100',
          AlertProperties: {
            DisplayNotification: true,
            HighlightCell: true,
          },
        },
        {
          Name: 'alert-success-github-watchers',
          Type: 'RelativeChange',
          MessageType: 'Success',
          Scope: {
            ColumnIds: ['github_watchers'],
          },
          Rule: 'ABSOLUTE_CHANGE([github_watchers], "DECREASE") = 20',
          AlertProperties: {
            DisplayNotification: true,
            HighlightCell: true,
          },
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'github_watchers',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

### Providing Relative Change Alerts in Initial State

Set `Type: 'RelativeChange'` so the Alert Wizard and validation treat the rule as relative change. AdapTable can also infer this from `ANY_CHANGE`, `PERCENT_CHANGE`, or `ABSOLUTE_CHANGE` in the `Rule`.

`Scope` limits which column edits are considered (same as [Data Change Alerts](https://www.adaptabletools.com/docs/handbook-alerting-data-change/index.md)). The `Rule` uses relative-change functions on the changing cell.

```ts [[1, 2, "Alert"], [1, 3, "AlertDefinitions"], [1, 6, "Type"], [1, 6, "RelativeChange"], [2, 8, "Scope"], [2, 9, "DataTypes"], [2, 11, "Rule"], [2, 11, "ANY_CHANGE"], [1, 19, "Type"], [2, 21, "Scope"], [2, 22, "ColumnIds"], [2, 24, "Rule"], [2, 24, "PERCENT_CHANGE"]]
const initialState: InitialState = {
  Alert: {
    AlertDefinitions: [
      {
        Name: 'alert-any-numeric-change',
        Type: 'RelativeChange',
        MessageType: 'Info',
        Scope: {
          DataTypes: ['number'],
        },
        Rule: 'ANY_CHANGE([name])',
        AlertProperties: {
          DisplayNotification: true,
          HighlightCell: true,
        },
      },
      {
        Name: 'alert-stars-percent-jump',
        Type: 'RelativeChange',
        MessageType: 'Warning',
        Scope: {
          ColumnIds: ['github_stars'],
        },
        Rule: 'PERCENT_CHANGE([github_stars]) > 50',
        AlertProperties: {
          DisplayNotification: true,
          HighlightCell: true,
          DisplaySystemStatusMessage: true,
        },
      },
    ],
  },
};
```
