CRingBuffer

CRingBuffer - Числовой кольцевой буфер с лёгким высокопроизводительным статистическим движком

среднее значение, дисперсию, стандартное отклонение, процентиль, z-оценки, отслеживание min/max и нормализованные значения — всё в O(1) до O(n log n).

Содержание:

1. Область применения
   
2. Два режима работы
3. Базовая статистика
4. Статистика Уэлфорда (численно устойчива, рекомендуется для больших ценовых уровней)
5. Процентили
6. Анализ z-оценки (три режима)
7. Отслеживание min/max (O(1))
8. Нормализация min-max
9. Логика заполнителей
10. Виртуальный индекс
11. Расширяемость через наследование (6 event hooks)
12. Снимок статистики через RBufStats (30+ метрик в одном объекте)
13. Преимущества
14. Пример
15. Статистические функции с первого взгляда
16. Обновления и поддержка

1. Область применения:

CRingBuffer разработан для разработчиков MQL5, которым нужен статистический анализ скользящих окон в индикаторах, советниках или библиотеках
.

Типичные сценарии использования:

- Непрерывное наблюдение за рынком (цена, спред, объём, значения ATR)
- Нормализация сигналов в диапазон [0,1] для скоринговых систем
- Обнаружение выбросов на основе z-оценки в реальном времени или в бэктесте
- Определение порогов на основе процентилей (устойчиво к таймфреймам)
- Построение собственных слоёв расчёта индикаторов через наследование
- Компонент в многослойных архитектурах классов
- Сбор данных в событийно-ориентированных системах с переменной длиной истории

Не подходит для:

- Анализа стакана заявок в реальном времени при очень высокой частоте тиков  (нет lock-free параллельной обработки)
- Хранения нечисловых данных

2. Два режима работы:

- Статический буфер: фиксированный размер окна, самые старые значения автоматически
  перезаписываются. Идеально для ATR-14, RSI-14 или любых скользящих окон.

- Динамический буфер: размер окна можно изменять во время выполнения. Отдельные значения
  можно удалять. Ёмкость увеличивается или уменьшается по мере необходимости.

3. Базовая статистика (всё O(1) после вставки):

- Сумма, сумма квадратов
- Арифметическое среднее
- Выборочная дисперсия и стандартное отклонение с поправкой Бесселя

4. Статистика Уэлфорда (численно устойчива, рекомендуется для больших ценовых уровней):

- Среднее Уэлфорда, дисперсия Уэлфорда, стандартное отклонение Уэлфорда
- Устойчива к эффектам потери точности в длинных рядах или при высоких ценовых уровнях
  (например, BTCUSD ~100 000 или индекс Nasdaq)

5. Процентили:

- getPercentile()  - один процентиль с линейной интерполяцией (Hyndman & Fan, метод 7)
- getPercentiles() - несколько процентилей за один отсортированный проход
- Заполнители (EMPTY_VALUE, NaN, Inf) автоматически отфильтровываются

6. Анализ z-оценки (три режима):

- getLastZScore()    - текущая z-оценка самого нового значения
- getZScoreAt()       - z-оценка без look-ahead для бэктестинга
- getZScores()         - expanding window (без look-ahead) или rolling  сразу для всех значений буфера

7. Отслеживание min/max (O(1)):

- Текущий минимум и максимум всех валидных значений
- Виртуальные позиции min и max доступны как индексы
- Диапазон (max - min) доступен в любой момент
- Сглаженная история диапазона для анализа трендов

8. Нормализация min-max:

- getNormalizedValue()     - нормализовать любое значение в [0,1]
- getNormalizedValueAt()  - нормализовать значение по виртуальному индексу
- getNormalizedValues()    - экспортировать все значения буфера в нормализованном виде
- Резервное значение 0.5 для постоянных данных (определённое поведение, не ошибка)

9. Логика заполнителей:

- EMPTY_VALUE, NaN и Inf распознаются автоматически
- Они занимают слот, но не учитываются ни в какой статистике
- Буферы индикаторов MQL5 изначально заполнены EMPTY_VALUE — эта
  фильтрация предотвращает статистические искажения без дополнительного кода

10. Виртуальный индекс:

- Единая адресация: индекс 0 = самое старое, индекс n-1 = самое новое значение
- Внутренняя механика кольцевого буфера полностью прозрачна для вызывающей стороны

11. Расширяемость через наследование (6 event hooks):

- OnAddValue()        - после каждой вставки
- OnRemoveValue()  - при удалении или перезаписи
- OnChangeValue()   - после replaceValue()
- OnChangeArray()   - после каждого структурного изменения
- OnSetMaxTotal()    - после изменения ёмкости
- OnShrink()             - после уменьшения буфера
- Все hooks срабатывают после полного обновления статистики

12. Снимок статистики через RBufStats (30+ метрик в одном объекте):

- Группа A: Базовая статистика (mean, variance, stddev, min, max, range, sum,
  total_count, valid_count, last_value, previous_value, oldest_value,
  min_index, max_index, avg_range, avg_diff, fill_rate)
- Группа B: Статистика Уэлфорда (welford_mean, welford_variance, welford_stddev)
- Группа C: Процентили (Q05, Q10, Q25, Median, Q75, Q90, Q95, IQR)
- Группа D: Z-оценка и нормализация (zscore, zscore_prev, zscore_delta,
  norm_last, norm_oldest)
- Метод валидации Validate(), конструктор копирования, operator=()

13. Преимущества:

- Не требуется собственный код кольцевого буфера: заменяет несколько сотен строк повторяющейся boilerplate-реализации
- Численно устойчивая методика Уэлфорда доступна параллельно с формулой суммы 
- Три режима z-оценки, включая режим без look-ahead для корректной оценки сигналов в бэктесте
- Автоматическая фильтрация заполнителей предотвращает статистические искажения из-за инициализации буферов индикаторов MQL5 значением EMPTY_VALUE
- Инкрементальное обновление всех статистик за O(1) после каждой вставки — без дорогого пересчёта при запросах
- Полностью расширяем через наследование и event hooks без изменения базового класса
- Единый виртуальный индекс скрывает сложность внутреннего кольцевого буфера
- Полная русская документация (справочник API, детали поведения, примеры кода, подводные камни)

14. Пример:

1. Скопируйте CRingBuffer.ex5 в нужный каталог проекта
2. Подключите его в MQL5-файле:

   #include "CRingBuffer_standalone.ex5"

3. Создайте экземпляр буфера:

   CRingBuffer buf(20, false);   // Статический буфер, ёмкость 20
   CRingBuffer dyn(20, true);    // Динамический буфер

4. Добавьте значения и получите статистику:

   buf.addValue(close[0]);
   double mean   = buf.getMean();
   double stddev = buf.getWelfordStdDev();
   double zscore = buf.getLastZScore();

Дополнительных зависимостей не требуется. Библиотека полностью автономна.

15. Статистические функции с первого взгляда

16. Обновления и поддержка:

- Поддержка исключительно через внутреннюю систему сообщений MQL5
- Сообщения об ошибках и предложения по улучшению обрабатываются оперативно