CRingBuffer

CRingBuffer - Numerischer Ringpuffer mit lightweight performanter Statistik-Engine

Mittelwert, Varianz, Standardabweichung, Perzentile, Z-Scores, Min/Max-Tracking und normalisierte Werte - alles in O(1) bis O(n log n).

Inhaltsverzeichnis:

1. Einsatzgebiet
   
2. Zwei Betriebsarten
3. Basisstatistik
4. Welford-Statistik (numerisch stabil, empfohlen für grosse Preisniveaus)
5. Perzentile
6. Z-Score-Analyse (drei Modi)
7. Min/Max-Tracking (O(1))
8. Min-Max-Normalisierung
9. Platzhalter-Logik
10. Virtueller Index
11. Erweiterbarkeit durch Vererbung (6 Event-Hooks)
12. Statistik-Snapshot via RBufStats (30+ Kennzahlen in einem Objekt)
13. Vorteile
14. Beispiel
15. Updates & Support

1. Einsatzgebiet:

CRingBuffer ist für MQL5-Entwickler konzipiert, die statistische Rolling-Window-Analysen in Indikatoren, Expert Advisors oder Bibliotheken
benötigen.

Typische Anwendungsszenarien:

- Gleitende Marktbeobachtung (Preis, Spread, Volumen, ATR-Werte)
- Normalisierung von Signalen auf [0,1] fuer Scoring-Systeme
- Z-Score-basierte Ausreissererkennung in Echtzeit oder im Backtest
- Perzentil-basierte Schwellenwertbestimmung (Timeframe-robust)
- Aufbau eigener Indikator-Berechnungsschichten durch Vererbung
- Komponente in Multi-Schicht-Klassenarchitekturen
- Datensammlung in event-basierten Systemen mit variabler Historienlaenge

Nicht geeignet für:

- Echtzeit-Orderbuch-Analysen mit sehr hoher Tickfrequenz  (keine Lock-freie Parallelverarbeitung)
- Speicherung von nicht-numerischen Daten

2. Zwei Betriebsarten:

- Statischer Buffer: feste Fenstergrösse, älteste Werte werden automatisch
  überschrieben. Ideal für ATR-14, RSI-14 oder beliebige Rolling-Windows.

- Dynamischer Buffer: Fenstergrössezur Laufzeit änderbar. Einzelne Werte
  entfernbar. Kapazität wächst oder schrumpft nach Bedarf.

3. Basisstatistik (alle O(1) nach Einfügevorgang):

- Summe, Quadratsumme
- Arithmetischer Mittelwert
- Bessel-korrigierte Stichprobenvarianz und Standardabweichung

4. Welford-Statistik (numerisch stabil, empfohlen für grosse Preisniveaus):

- Welford-Mittelwert, Welford-Varianz, Welford-Standardabweichung
- Robust gegen Auslöschungseffekte bei langen Serien oder hohen Preisniveaus
  (z.B. BTCUSD ~100.000 oder Nasdaq-Index)

5. Perzentile:

- getPercentile()  - einzelnes Perzentil mit linearer Interpolation (Hyndman & Fan, Methode 7)
- getPercentiles() - mehrere Perzentile in einem einzigen sortierten Durchlauf
- Platzhalter (EMPTY_VALUE, NaN, Inf) werden automatisch herausgefiltert

6. Z-Score-Analyse (drei Modi):

- getLastZScore()    - aktueller Z-Score des neuesten Wertes
- getZScoreAt()       - look-ahead-freier Z-Score für Backtesting
- getZScores()         - expanding window (look-ahead-frei) oder rolling  für alle Bufferwerte gleichzeitig

7. Min/Max-Tracking (O(1)):

- Laufendes Minimum und Maximum aller gültigen Werte
- Virtuelle Positionen von Min und Max als Indizes abrufbar
- Spannweite (max - min) jederzeit verfügbar
- Geglättete Range-Historie für Trendanalysen

8. Min-Max-Normalisierung:

- getNormalizedValue()     - beliebigen Wert auf [0,1] normalisieren
- getNormalizedValueAt()  - Wert an virtuellem Index normalisieren
- getNormalizedValues()    - alle Bufferwerte normalisiert exportieren
- Fallback 0.5 bei konstanten Daten (definiertes Verhalten, kein Fehler)

9. Platzhalter-Logik:

- EMPTY_VALUE, NaN und Inf werden automatisch erkannt
- Sie belegen einen Slot, werden aber in keiner Statistik berücksichtigt
- MQL5-Indikatorbuffer sind zu Beginn mit EMPTY_VALUE gefüllt - diese
  Filterung verhindert Statistikverzerrung ohne zusätzlichen Code

10. Virtueller Index:

- Einheitliche Adressierung: Index 0 = ältester, Index n-1 = neuester Wert
- Interne Ringpuffer-Mechanik vollständig transparent für den Aufrufer

11. Erweiterbarkeit durch Vererbung (6 Event-Hooks):

- OnAddValue()        - nach jedem Einfügevorgang
- OnRemoveValue()  - bei Entfernen oder Überschreiben
- OnChangeValue()   - nach replaceValue()
- OnChangeArray()   - nach jeder strukturellen Änderung
- OnSetMaxTotal()    - nach Kapazitaetsänderung
- OnShrink()             - nach Pufferverkleinerung
- Alle Hooks feuern nach vollständiger Statistikaktualisierung

12. Statistik-Snapshot via RBufStats (30+ Kennzahlen in einem Objekt):

- Gruppe A: Basisstatistik (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)
- Gruppe B: Welford-Statistik (welford_mean, welford_variance, welford_stddev)
- Gruppe C: Perzentile (Q05, Q10, Q25, Median, Q75, Q90, Q95, IQR)
- Gruppe D: Z-Score und Normalisierung (zscore, zscore_prev, zscore_delta,
  norm_last, norm_oldest)
- Validierungsmethode Validate(), Copy-Konstruktor, operator=()

13. Vorteile:

- Kein eigener Ringpuffer-Code notwendig: ersetzt mehrere hundert Zeilen wiederkehrender Boilerplate-Implementierung
- Numerisch stabile Welford-Methode parallel zur Summenformel verfügbar 
- Drei Z-Score-Modi inklusive look-ahead-freiem Modus für Backtest-konforme Signalauswertung
- Automatische Platzhalter-Filterung verhindert Statistikverzerrung durch EMPTY_VALUE-Initialisierung von MQL5-Indikatorbuffern
- Inkrementelle O(1)-Aktualisierung aller Statistiken nach jedem Insert - keine teure Neuberechnung bei Abfragen
- Vollständig erweiterbar durch Vererbung und Event-Hooks ohne Änderung der Basisklasse
- Einheitlicher virtueller Index versteckt interne Ringpuffer-Komplexität
- Vollständige deutsche Dokumentation (API-Referenz, Verhaltensdetails, Codebeispiele, Fallstricke)

14. Beispiel:

1. CRingBuffer.ex5 in das gewünschte Projektverzeichnis kopieren
2. In der MQL5-Datei einbinden:

   #include "CRingBuffer_standalone.ex5"

3. Buffer instanziieren:

   CRingBuffer buf(20, false);   // Statischer Buffer, Kapazitaet 20
   CRingBuffer dyn(20, true);    // Dynamischer Buffer

4. Werte hinzufügen und Statistiken abrufen:

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

Keine weiteren Abhängigkeiten. Die Bibliothek ist vollständig selbstständig.

15. Statistikfunktionen im Überblick

16. Updates & Support:

- Support ausschliesslich ueber das MQL5-interne Kommunikationssystem
- Fehlermeldungen und Verbesserungsvorschläge werden zeitnah beantwortet