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

***

***


---

# 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://docs.sov.ai/api-reference/extensions/cusum.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.