> For the complete documentation index, see [llms.txt](https://docs.sov.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sov.ai/api-reference/extensions/cusum.md).

# Cusum

**Module:** `sovai.extensions.cusum`

## Classes

### `CUSUM_Detector`

```python
class CUSUM_Detector
```

CUSUM Change Point Detector Class

Example:

```
detector = CUSUM_Detector(warmup_period=20, delta=15, threshold=30)
data = [12.3, 14.5, 15.6, 16.8, 17.9, 20.2, 25.7, 30.2, 32.5, 32.9, 33.0, 32.2, 31.8, 30.5, 30.1]
pos_changes, neg_changes, change_points = detector.detect_change_points(data)
detector.plot_change_points(data, change_points, pos_changes, neg_changes)
```

**Attributes**

* `warmup_period`
* `delta`
* `threshold`

**Methods**

### `__init__()`

```python
def __init__(self, warmup_period = 10, delta = 10, threshold = 20)
```

Initializes the Change Point Detector with the specified parameters.

**Parameters**

| Parameter       | Type    | Description                                                                                |
| --------------- | ------- | ------------------------------------------------------------------------------------------ |
| `warmup_period` | `int`   | The number of initial observations before starting to detect change points. Default is 10. |
| `delta`         | `float` | Sensitivity parameter for detecting changes. Default is 10.                                |
| `threshold`     | `float` | Threshold for detecting a change point. Default is 20.                                     |

***

### `predict_next()`

```python
def predict_next(self, observation)
```

Predicts the next data point and detects change points.

**Parameters**

| Parameter     | Type    | Description     |
| ------------- | ------- | --------------- |
| `observation` | `float` | New data point. |

**Returns**

* pos\_change (numpy array): Cumulative sum for positive changes.
* neg\_change (numpy array): Cumulative sum for negative changes.
* is\_changepoint (bool): Indicates if a change point is detected.

***

### `detect_change_points()`

```python
def detect_change_points(self, data)
```

Detects change points in the given data using the CUSUM detector.

**Parameters**

| Parameter | Type          | Description                 |
| --------- | ------------- | --------------------------- |
| `data`    | `numpy array` | Data points to be analyzed. |

**Returns**

* pos\_changes (numpy array): Positive cumulative sum values.
* neg\_changes (numpy array): Negative cumulative sum values.
* change\_points (numpy array): Detected change points indices.

***

### `plot_change_points()`

```python
def plot_change_points(self, data, change_points, pos_changes, neg_changes)
```

Plots data with detected change points and cumulative sums.

**Parameters**

| Parameter       | Type          | Description                             |
| --------------- | ------------- | --------------------------------------- |
| `data`          | `numpy array` | Original data points.                   |
| `change_points` | `list`        | List of detected change points.         |
| `pos_changes`   | `list`        | List of positive cumulative sum values. |
| `neg_changes`   | `list`        | List of negative cumulative sum values. |

***

***

### `ProbCUSUM_Detector`

```python
class ProbCUSUM_Detector
```

A class to detect change points in sequential data using the Probabilistic Cumulative Sum (CUSUM) algorithm.

Example:

```
detector = ProbCUMSUM_Detector(warmup_period=10, threshold_probability=0.001)
data = [10.2, 11.5, 12.6, 12.8, 12.9, 13.2, 12.7, 12.5, 12.3, 12.9, 25.0, 12.2, 11.8, 10.5, 10.1]
probabilities, change_points = detector.detect_change_points(data)
detector.plot_change_points(data, change_points, probabilities)
```

**Attributes**

* `warmup_period`
* `threshold_probability`
* `running_sum`

**Methods**

### `__init__()`

```python
def __init__(self, warmup_period = 10, threshold_probability = 0.001)
```

Initializes the Probabilistic CUSUM Detector with the specified parameters.

**Parameters**

| Parameter               | Type    | Description                                                                                |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `warmup_period`         | `int`   | The number of initial observations before starting to detect change points. Default is 10. |
| `threshold_probability` | `float` | The threshold probability below which a change point is detected. Default is 0.001.        |

***

### `predict_next()`

```python
def predict_next(self, observation)
```

Predicts the probability of a change point in the next observation.

**Parameters**

| Parameter     | Type    | Description                           |
| ------------- | ------- | ------------------------------------- |
| `observation` | `float` | The next observation in the sequence. |

**Returns**

* probability (float): The probability of a change point in the next observation.
* is\_changepoint (bool): True if a change point is detected, False otherwise.

***

### `detect_change_points()`

```python
def detect_change_points(self, data)
```

Detects change points in the given data using the CUSUM detector.

**Parameters**

| Parameter | Type | Description                             |
| --------- | ---- | --------------------------------------- |
| `data`    | —    | numpy array Data points to be analyzed. |

**Returns**

* probabilities: numpy array Probability values for each data point.
* change\_points: numpy array Detected change points indices.

***

### `plot_change_points()`

```python
def plot_change_points(self, data, change_points, probabilities)
```

Plots data with detected change points and probabilities.

**Parameters**

| Parameter       | Type | Description                                                 |
| --------------- | ---- | ----------------------------------------------------------- |
| `data`          | —    | numpy array Original data points.                           |
| `change_points` | —    | list List of detected change points.                        |
| `probabilities` | —    | list List of probabilities associated with each data point. |

***

***

### `ChartCUSUM_Detector`

```python
class ChartCUSUM_Detector
```

Change Point Detector using CUSUM Control Chart.

Example:

```
detector = ChartCUSUM_Detector(warmup_period=20, level=2, deviation_type='sqr-dev')
np.random.seed(0)
data = np.concatenate([np.random.normal(0, 1, 30), np.random.normal(3, 1, 30)])
upper_limits, lower_limits, cusums, change_points = detector.detect_change_points(data)
detector.plot_change_points(data, change_points, cusums, upper_limits, lower_limits)
```

**Attributes**

* `warmup_period`
* `level`
* `deviation_type`

**Methods**

### `__init__()`

```python
def __init__(self, warmup_period = 10, level = 3, deviation_type = 'sqr-dev')
```

Initializes the Change Point Detector with the specified parameters.

**Parameters**

| Parameter       | Type  | Description                                                                                    |
| --------------- | ----- | ---------------------------------------------------------------------------------------------- |
| `warmup_period` | `int` | The warmup period for the detector. Must be equal or greater than 10.                          |
| `level`         | `int` | The level parameter for the CUSUM algorithm.                                                   |
| `type`          | `str` | The type of deviation used in CUSUM algorithm. 'sqr-dev' for square deviation, else deviation. |

***

### `predict_next()`

```python
def predict_next(self, observation)
```

Predicts the next data point and detects change points.

**Parameters**

| Parameter     | Type    | Description                     |
| ------------- | ------- | ------------------------------- |
| `observation` | `float` | The next data point to predict. |

**Returns**

* upper (float): The upper limit of the CUSUM.
* lower (float): The lower limit of the CUSUM.
* cusum (float): The current value of the CUSUM.
* is\_changepoint (bool): Indicates if a change point is detected.

***

### `detect_change_points()`

```python
def detect_change_points(self, data)
```

Detects change points in the given data using the CUSUM detector.

**Parameters**

| Parameter | Type         | Description                          |
| --------- | ------------ | ------------------------------------ |
| `data`    | `np.ndarray` | The data to detect change points in. |

**Returns**

* upper\_limits (np.ndarray): Upper limits of the CUSUM for each observation.
* lower\_limits (np.ndarray): Lower limits of the CUSUM for each observation.
* cusums (np.ndarray): Cumulative sums of deviations.
* change\_points (np.ndarray): Indices of detected change points.

***

### `plot_change_points()`

```python
def plot_change_points(self, data, change_points, cusums, upper_limits, lower_limits)
```

Plots data with detected change points and cumulative sums.

**Parameters**

| Parameter       | Type         | Description                                     |
| --------------- | ------------ | ----------------------------------------------- |
| `data`          | `np.ndarray` | The original data.                              |
| `change_points` | `np.ndarray` | Indices of detected change points.              |
| `cusums`        | `np.ndarray` | Cumulative sums of deviations.                  |
| `upper_limits`  | `np.ndarray` | Upper limits of the CUSUM for each observation. |
| `lower_limits`  | `np.ndarray` | Lower limits of the CUSUM for each observation. |

***

***