CRingBuffer
- Библиотеки
- Christian Stern
- Версия: 1.0
- Активации: 10
CRingBuffer - Числовой кольцевой буфер с лёгким высокопроизводительным статистическим движком
CRingBuffer — это мощная библиотека MQL5 для числового анализа скользящих окон. После каждой вставки она сразу предоставляет
среднее значение, дисперсию, стандартное отклонение, процентиль, z-оценки, отслеживание min/max и нормализованные значения — всё в O(1) до O(n log n).
Содержание:
- Область применения
- Два режима работы
- Базовая статистика
- Статистика Уэлфорда (численно устойчива, рекомендуется для больших ценовых уровней)
- Процентили
- Анализ z-оценки (три режима)
- Отслеживание min/max (O(1))
- Нормализация min-max
- Логика заполнителей
- Виртуальный индекс
- Расширяемость через наследование (6 event hooks)
- Снимок статистики через RBufStats (30+ метрик в одном объекте)
- Преимущества
- Пример
- Статистические функции с первого взгляда
- Обновления и поддержка
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. Статистические функции с первого взгляда
| Группа | Методы | Польза |
|---|---|---|
| Базовая статистика | getSum(), getSumSq(), getMean(), getVariance(), getStdDev() | Предоставляет классические метрики для среднего значения, разброса и общей суммы валидных значений. |
| Статистика Уэлфорда | getWelfordMean(), getWelfordVariance(), getWelfordStdDev() | Предлагает численно более устойчивые альтернативы для длинных рядов, высоких ценовых уровней и малых различий между значениями. |
| Отслеживание min/max | getMin(), getMax(), getMinIndex(), getMaxIndex(), getMinMaxRange() | Описывает экстремальные значения, их позиции и текущий диапазон буфера для быстрой оценки состояния. |
| История диапазона | getAverageRange(), getRangeHistory() | Показывает, как диапазон меняется во времени, и поддерживает анализ волатильности. |
| Среднее изменение | getAverageDiff() | Измеряет среднее абсолютное изменение между последовательными валидными значениями и помогает оценить рыночную динамику. |
16. Обновления и поддержка:
- Поддержка исключительно через внутреннюю систему сообщений MQL5
- Сообщения об ошибках и предложения по улучшению обрабатываются оперативно
