mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-26 06:18:05 +00:00
Refactor documentation for clarity and detail
This commit is contained in:
Miha Kralj
+92
-56
@@ -1,95 +1,131 @@
|
||||
# CONV: Convolution
|
||||
# CONV: Convolution Indicator
|
||||
|
||||
## Overview and Purpose
|
||||
## What It Does
|
||||
|
||||
The Convolution (CONV) is a flexible technical indicator that allows traders to apply any arbitrary weighting scheme (kernel) to price data. Rooted in signal processing principles developed in the 1950-60s, convolution filtering was later adapted to financial markets in the 1990s as digital signal processing techniques gained popularity in technical analysis. Convolution provides a generalized framework that enables traders to create customized moving averages with specific filtering characteristics, either by designing their own weight distributions or using predefined kernels.
|
||||
The Convolution Indicator (CONV) is a generalized filtering tool that applies a custom set of weights (a "kernel") to a window of historical data. Unlike standard moving averages that use fixed formulas (equal weights for SMA, linear for WMA), CONV allows you to define *any* weighting scheme you can imagine. It is the fundamental building block for creating custom digital signal processing filters, edge detectors, or specialized smoothing algorithms.
|
||||
|
||||
## Core Concepts
|
||||
## Historical Context
|
||||
|
||||
* **Customizable weighting:** Convolution allows any sequence of weights to be applied to price data, enabling precise control over filtering behavior.
|
||||
* **Kernel flexibility:** Supports both simple weight distributions (like those used in SMA) and complex multi-lobe designs with specialized filtering properties.
|
||||
* **Market application:** Particularly valuable for traders who need to design specialized filters for specific market conditions or trading strategies.
|
||||
* **Raw Dot Product:** The indicator calculates the dot product of the kernel and the price window. It does not automatically normalize the result, giving the user complete control over the magnitude.
|
||||
Convolution is a mathematical operation fundamental to signal processing, image processing, and physics. In finance, it gained traction with the rise of quantitative trading, where analysts needed more flexibility than standard indicators provided. By treating price data as a signal and applying convolution kernels, traders can design filters that isolate specific frequencies, detect patterns, or perform advanced smoothing that adapts to specific market characteristics.
|
||||
|
||||
The core innovation of convolution is its implementation of the fundamental convolution operation from signal processing. This provides a unified framework that can replicate many standard moving averages through appropriate kernel selection, while also allowing for experimentation with novel weight distributions that aren't available in standard indicators.
|
||||
## How It Works
|
||||
|
||||
## Parameters
|
||||
### The Core Idea
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `kernel` | `double[]` | Array of weights defining the filter. `kernel[0]` applies to the oldest data, `kernel[n-1]` to the newest. |
|
||||
Imagine a sliding window over your price data. You have a list of "weights" (the kernel) of the same length as the window. To get the result for the current bar, you multiply each price in the window by its corresponding weight and sum them up.
|
||||
|
||||
**Note:** The `period` or `length` of the indicator is determined automatically by the length of the provided kernel array.
|
||||
- If your kernel is `[0.2, 0.2, 0.2, 0.2, 0.2]`, you've recreated a 5-period SMA.
|
||||
- If your kernel is `[0.1, 0.2, 0.3, 0.4]`, you've recreated a 4-period WMA (unnormalized).
|
||||
- If your kernel is `[-1, 1]`, you've created a momentum indicator (Price - Previous Price).
|
||||
|
||||
## Formula
|
||||
### Mathematical Foundation
|
||||
|
||||
$$
|
||||
Conv_t = \sum_{i=0}^{n-1} (kernel_i \times P_{t-(n-1)+i})
|
||||
$$
|
||||
For a kernel $K$ of length $n$ and a price series $P$:
|
||||
|
||||
Where:
|
||||
$$CONV_t = \sum_{i=0}^{n-1} (P_{t-i} \cdot K_{n-1-i})$$
|
||||
|
||||
* $n$ is the length of the kernel.
|
||||
* $P$ is the price series.
|
||||
* $kernel_i$ is the weight at index $i$.
|
||||
In our implementation, the kernel is applied such that the last element of the kernel ($K_{n-1}$) multiplies the most recent price ($P_t$), and the first element ($K_0$) multiplies the oldest price in the window ($P_{t-n+1}$).
|
||||
|
||||
> ⚠️ **Important:** The implementation calculates the raw dot product. If you intend to create a Moving Average, ensure your kernel weights sum to 1.0. If they sum to something else, the output will be scaled accordingly.
|
||||
### Implementation Details
|
||||
|
||||
## C# Implementation
|
||||
The `Conv` indicator uses a **RingBuffer** to store the price history efficiently. The calculation is a dot product between the kernel and the buffered data.
|
||||
|
||||
### Standard Usage
|
||||
- **Update Complexity:** O(K), where K is the kernel length.
|
||||
- **Memory:** O(K) to store the buffer and the kernel.
|
||||
- **Optimization:** We use `Span<T>` and SIMD-optimized dot product operations where available to ensure high performance even with large kernels.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Parameter | Default | Purpose | Adjustment Guidelines |
|
||||
|-----------|---------|---------|----------------------|
|
||||
| Kernel | (Required) | Array of weights | Defines the filter behavior. Must not be empty. |
|
||||
|
||||
**Note:** The kernel is not automatically normalized. If you want a moving average that tracks price levels, the sum of your kernel weights should equal 1.0. If the sum is 0 (e.g., `[-1, 1]`), it will act as an oscillator.
|
||||
|
||||
## C# Usage
|
||||
|
||||
### Streaming Updates (Single Instance)
|
||||
|
||||
```csharp
|
||||
// Create a custom weighted moving average (weights sum to 1.0)
|
||||
double[] weights = { 0.1, 0.2, 0.3, 0.4 };
|
||||
using QuanTAlib;
|
||||
|
||||
// Create a custom kernel (e.g., a 3-period weighted average)
|
||||
double[] weights = { 0.1, 0.3, 0.6 };
|
||||
var conv = new Conv(weights);
|
||||
|
||||
TValue result = conv.Update(new TValue(DateTime.Now, 100.0));
|
||||
Console.WriteLine(result.Value);
|
||||
// Process each new bar
|
||||
TValue result = conv.Update(new TValue(timestamp, closePrice));
|
||||
Console.WriteLine($"Conv: {result.Value:F2}");
|
||||
```
|
||||
|
||||
### Span API (High Performance)
|
||||
### Batch Processing (Historical Data)
|
||||
|
||||
```csharp
|
||||
double[] weights = { 0.1, 0.2, 0.3, 0.4 };
|
||||
ReadOnlySpan<double> input = ...;
|
||||
Span<double> output = new double[input.Length];
|
||||
// TSeries API
|
||||
TSeries prices = ...;
|
||||
double[] kernel = { 0.2, 0.2, 0.2, 0.2, 0.2 }; // 5-period SMA
|
||||
TSeries sma5 = Conv.Batch(prices, kernel);
|
||||
|
||||
Conv.Batch(input, output, weights);
|
||||
// Span API (High Performance)
|
||||
double[] prices = new double[1000];
|
||||
double[] output = new double[1000];
|
||||
double[] edgeDetector = { -1, 1 }; // Simple difference
|
||||
Conv.Batch(prices.AsSpan(), output.AsSpan(), edgeDetector);
|
||||
```
|
||||
|
||||
### Bar Correction
|
||||
### Bar Correction (isNew Parameter)
|
||||
|
||||
```csharp
|
||||
var conv = new Conv(weights);
|
||||
var conv = new Conv(new[] { 0.5, 0.5 });
|
||||
|
||||
// Initial update for the bar
|
||||
conv.Update(new TValue(time, 100.0), isNew: true);
|
||||
// New bar
|
||||
conv.Update(new TValue(time, 100), isNew: true);
|
||||
|
||||
// Update with corrected price for the same bar
|
||||
conv.Update(new TValue(time, 101.0), isNew: false);
|
||||
// Intra-bar update
|
||||
conv.Update(new TValue(time, 101), isNew: false); // Replaces 100 with 101
|
||||
```
|
||||
|
||||
## Interpretation Details
|
||||
## Performance Profile
|
||||
|
||||
Convolution can be used in various ways depending on the kernel design:
|
||||
| Operation | Complexity | Description |
|
||||
|-----------|------------|-------------------|
|
||||
| Streaming update | O(K) | Linear scan (dot product) of the kernel |
|
||||
| Bar correction | O(K) | Re-calculates dot product |
|
||||
| Batch processing | O(N * K) | Sliding window dot product |
|
||||
| Memory footprint | O(K) | RingBuffer + Kernel array |
|
||||
|
||||
* **Trend identification:** With appropriate kernels (e.g., Gaussian, SMA weights), convolution can identify trends while filtering out noise.
|
||||
* **Specialized filtering:** Custom kernels can be designed to target specific price patterns or cycles.
|
||||
* **Moving average replication:** Convolution can replicate virtually any other moving average by using the appropriate kernel.
|
||||
* **Differentiation:** If weights sum to 0 (e.g., `[-1, 1]`), it acts as a momentum or rate-of-change indicator.
|
||||
* **Experimental strategies:** Enables testing of novel filtering approaches not available in standard indicators.
|
||||
## Interpretation
|
||||
|
||||
## Limitations and Considerations
|
||||
### Trading Signals
|
||||
|
||||
* **Knowledge requirement:** Requires understanding of convolution and filter design principles.
|
||||
* **Parameter complexity:** More parameters to optimize compared to standard moving averages.
|
||||
* **Potential overfitting:** Easy to create kernels that work well on historical data but fail on future data.
|
||||
* **Computational demands:** Slightly higher computational requirements than hardcoded implementations, though optimized with SIMD in this library.
|
||||
* **Validation necessity:** Custom kernels require thorough testing to ensure desired filtering characteristics.
|
||||
Signals depend entirely on the kernel you design:
|
||||
|
||||
- **Smoothing:** Use positive weights that sum to 1. (e.g., Gaussian, Triangle).
|
||||
- **Differentiation:** Use weights that sum to 0 to detect rate of change. (e.g., `[-1, 1]` for velocity, `[1, -2, 1]` for acceleration).
|
||||
- **Edge Detection:** Use kernels like `[-1, 0, 1]` (Sobel-like) to detect sharp price movements.
|
||||
|
||||
### When It Works Best
|
||||
|
||||
- **Custom Research:** When standard indicators don't fit your specific hypothesis.
|
||||
- **Signal Processing:** When applying filters from other domains (audio, image) to financial time series.
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
This implementation makes specific trade-offs:
|
||||
|
||||
### Choice: No Automatic Normalization
|
||||
|
||||
- **Alternative:** Automatically divide weights by their sum.
|
||||
- **Trade-off:** User must normalize manually if desired.
|
||||
- **Rationale:** Allows for oscillators (sum=0) and amplifiers (sum > 1), providing maximum flexibility.
|
||||
|
||||
### Choice: RingBuffer Implementation
|
||||
|
||||
- **Alternative:** Array copy.
|
||||
- **Trade-off:** Slightly complex indexing logic.
|
||||
- **Rationale:** Zero allocation during updates is critical for high-frequency trading applications.
|
||||
|
||||
## References
|
||||
|
||||
* Smith, S.W. "The Scientist and Engineer's Guide to Digital Signal Processing," Chapter 7: Properties of Convolution
|
||||
* Ehlers, J.F. "Cycle Analytics for Traders," Wiley, 2013
|
||||
* [Convolution on Wikipedia](https://en.wikipedia.org/wiki/Convolution)
|
||||
- Smith, Steven W. "The Scientist and Engineer's Guide to Digital Signal Processing." California Technical Publishing, 1997.
|
||||
- Ehlers, John F. "Cycle Analytics for Traders." Wiley, 2013.
|
||||
|
||||
Reference in New Issue
Block a user