normalization of methods

lib/dynamics/qstick/Qstick.md

@@ -0,0 +1,143 @@
+# QSTICK: Qstick Indicator
+
+> "The average candlestick body reveals the market's true conviction."
+
+Developed by Tushar Chande, the Qstick indicator measures the average difference between closing and opening prices over a lookback period. It quantifies whether bars are predominantly bullish (closing above opens) or bearish (closing below opens), providing a smoothed view of candlestick body direction and magnitude.
+
+## Historical Context
+
+Tushar Chande introduced the Qstick as part of his work on candlestick pattern quantification in the early 1990s. While traditional candlestick analysis relies on visual pattern recognition, Qstick provides a numerical measure that can be systematically tracked and used for algorithmic trading.
+
+The indicator addresses a fundamental question: "On average, are prices closing higher or lower than they open?" This simple metric captures intrabar momentum that other indicators measuring close-to-close changes may miss.
+
+## Architecture
+
+### 1. Body Difference Calculation
+
+The core input is the difference between close and open:
+
+```
+diff = Close - Open
+```
+
+- **Positive diff**: Bullish bar (white/green candle)
+- **Negative diff**: Bearish bar (black/red candle)
+- **Zero diff**: Doji (open equals close)
+
+### 2. Moving Average Smoothing
+
+The raw differences are smoothed using either SMA or EMA:
+
+**SMA Mode:**
+$$\text{Qstick} = \frac{1}{n} \sum_{i=0}^{n-1} (Close_i - Open_i)$$
+
+**EMA Mode:**
+$$\text{Qstick}_t = \alpha \cdot diff_t + (1 - \alpha) \cdot \text{Qstick}_{t-1}$$
+
+where $\alpha = \frac{2}{period + 1}$
+
+### 3. State Management
+
+For real-time bar correction (isNew=false), the indicator maintains:
+- `_sum` / `_savedSum`: Running sum for SMA
+- `_emaValue` / `_savedEmaValue`: Current EMA value
+- `_count` / `_savedCount`: Bar count for warmup
+
+## Parameters
+
+| Parameter | Type | Default | Valid Range | Description |
+|-----------|------|---------|-------------|-------------|
+| `period` | int | 14 | ≥ 1 | Lookback period for moving average |
+| `useEma` | bool | false | true/false | Use EMA (true) or SMA (false) |
+
+## Mathematical Foundation
+
+### Formula
+
+```
+Qstick = MA(Close - Open, period)
+```
+
+### Interpretation
+
+| Qstick Value | Market Condition |
+|--------------|------------------|
+| > 0 | Bullish momentum (closes above opens) |
+| < 0 | Bearish momentum (closes below opens) |
+| = 0 | Neutral (balanced open/close) |
+| Rising | Increasing bullish pressure |
+| Falling | Increasing bearish pressure |
+
+### Signal Generation
+
+- **Buy Signal**: Qstick crosses above zero
+- **Sell Signal**: Qstick crosses below zero
+- **Divergence**: Price making new highs while Qstick making lower highs suggests weakening momentum
+
+## Performance Profile
+
+### Operation Count (Streaming Mode)
+
+| Operation | SMA Mode | EMA Mode |
+|-----------|----------|----------|
+| ADD/SUB | 3 | 2 |
+| MUL | 0 | 1 |
+| DIV | 1 | 0 |
+| FMA | 0 | 1 |
+| Memory | O(period) | O(1) |
+
+### Complexity
+
+- **Time**: O(1) per bar for both modes
+- **Space**: O(period) for SMA, O(1) for EMA
+
+### Quality Metrics
+
+| Metric | Score | Notes |
+|--------|-------|-------|
+| Accuracy | 10/10 | Exact calculation |
+| Timeliness | 8/10 | Lag proportional to period |
+| Overshoot | 2/10 | Smooth, no overshoot |
+| Smoothness | 8/10 | SMA smoother than EMA |
+
+## Validation
+
+| Library | Status | Notes |
+|---------|--------|-------|
+| TA-Lib | ✓ | Not available (implement locally) |
+| Skender | ✓ | Validated against Qstick |
+| OoplesFinance | ✓ | Validated |
+
+## Common Pitfalls
+
+1. **Ignoring Volume**: Qstick weights all bars equally; consider volume-weighted variants for more accuracy
+2. **Range Dependence**: Absolute values depend on price scale; normalize for comparison across instruments
+3. **Period Selection**: Short periods (5-8) for trading signals; long periods (20+) for trend identification
+4. **Gap Sensitivity**: Large gaps (open ≠ previous close) can distort readings
+5. **Flat Markets**: Near-zero readings indicate indecision, not necessarily reversal
+
+## Usage Example
+
+```csharp
+// Create Qstick with 14-period SMA
+var qstick = new Qstick(14);
+
+// Update with bar data
+foreach (var bar in bars)
+{
+    var result = qstick.Update(bar);
+    if (qstick.IsHot)
+    {
+        Console.WriteLine($"Qstick: {result.Value:F4}");
+    }
+}
+
+// Or use EMA mode
+var qstickEma = new Qstick(14, useEma: true);
+```
+
+## References
+
+1. Chande, T. S. (1994). *The New Technical Trader*. John Wiley & Sons.
+2. Chande, T. S., & Kroll, S. (1994). *Beyond Technical Analysis*. John Wiley & Sons.
+3. Kirkpatrick, C. D., & Dahlquist, J. R. (2015). *Technical Analysis: The Complete Resource for Financial Market Technicians*. FT Press.