> For the complete documentation index, see [llms.txt](https://ats-doc.gitbook.io/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ats-doc.gitbook.io/v1/customizations/adding-an-indicator.md).

# Adding an Indicator

To add a custom indicator to the project, follow these guidelines. Every custom indicator must extend the `BaseIndicator` class and adhere to the specified directory and file structure.

## Directory Structure

1. Add your custom indicator class to the `custom_modules/indicators/` directory:

   ```bash
   custom_modules/indicators/<name_of_your_indicator>.py
   ```
2. Implement your indicator class in a Python file named after your indicator.

## Implementing a Custom Indicator

1. **Class Definition**:

   * Your indicator class must extend the `BaseIndicator` class.
   * Here's an example of a custom indicator implementation:<br>

   ```python
   from ats.indicators.base_indicator import BaseIndicator

   class CustomIndicator(BaseIndicator):
       def running_calc(self, popped_data_point, new_data_point) -> float:
           """
           Calculates the indicator in a running window.
           Args:
               popped_data_point: The data point removed from the time series (if window size is reached).
               new_data_point: The new data point being added.

           Returns:
               The new calculated data point.
           """
           # Example logic for a moving average indicator
           if popped_data_point is not None:
               self.sums -= popped_data_point
           else:
               self.sums = 0

           self.sums += new_data_point
           self.result = self.sums / self.N
           return new_data_point
   ```
2. **Requirements**:
   * Implement the `running_calc(popped_data_point, new_data_point)` method to define the indicator's calculation logic.
   * Use the `self.time_series` to maintain the data points within the indicator's rolling window (`N` size specified in the config).
   * Update `self.result` with the calculated result of the indicator in each window.
3. **State Management**:
   * The `BaseIndicator` class maintains an internal time series and state. You can extend this state or use additional internal variables for more complex calculations.
4. **Configuration**:
   * Indicators must be initialized with a `config` dictionary containing all required parameters (e.g., the window size `N`).

## Accessing and Using Indicators

Custom indicators can be used in strategies or other components by importing and instantiating them:

```python
from ats.utils.general import helpers as general_helpers

config = {"N": 5}  # Configuration of the sliding window size
indicator_class = general_helpers.get_class_from_namespace("indicators:custom_indicator")
indicator = indicator_class(config)

# Add data points to the indicator
indicator.add(1.0)
indicator.add(2.0)

# Check if the indicator is ready
if indicator.is_ready():
    print(f"Indicator result: {indicator.result}")
```

## Example Directory Structure

Assuming the indicator is named `custom_indicator`:

```
custom_modules/
├── indicators/
│   ├── custom_indicator.py
```

## Notes on Indicator Logic

* **Rolling Window Calculations**: The `running_calc()` method provides a streamlined way to perform calculations within a rolling window. When a new data point is added, the oldest data point is removed (if the window size is reached).
* **State Handling**: Use the `self.states` attribute if you need to maintain additional state data across calculations.
* **Thread Safety**: The `BaseIndicator` class is not thread-safe. If your use case requires thread safety, you should implement appropriate synchronization mechanisms.

By following these guidelines, your custom indicator will integrate seamlessly with the project, ensuring compatibility and adherence to project conventions. This modular structure allows for easy addition, management, and testing of new indicators.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://ats-doc.gitbook.io/v1/customizations/adding-an-indicator.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.