vasily/TCPDashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor technical indicators module and enhance structure

Browse Source 
- Introduced a dedicated sub-package for technical indicators under `data/common/indicators/`, improving modularity and maintainability.
- Moved `TechnicalIndicators` and `IndicatorResult` classes to their respective files, along with utility functions for configuration management.
- Updated import paths throughout the codebase to reflect the new structure, ensuring compatibility.
- Added comprehensive safety net tests for the indicators module to verify core functionality and prevent regressions during refactoring.
- Enhanced documentation to provide clear usage examples and details on the new package structure.

These changes improve the overall architecture of the technical indicators module, making it more scalable and easier to manage.
This commit is contained in:
Vasily.onl
2025-06-07 01:32:21 +08:00
parent e7ede7f329
commit c8d8d980aa
9 changed files with 530 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/modules/technical-indicators.md
View File

@@ -4,7 +4,17 @@ The Technical Indicators module provides a suite of common technical analysis to
## Overview
The module has been refactored to be **DataFrame-centric**. All calculation methods now expect a pandas DataFrame with a `DatetimeIndex` and the required OHLCV columns (`open`, `high`, `low`, `close`, `volume`). This change simplifies the data pipeline, improves performance through vectorization, and ensures consistency across the platform.
The module has been refactored into a dedicated package structure under `data/common/indicators/`. All calculation methods now expect a pandas DataFrame with a `DatetimeIndex` and the required OHLCV columns (`open`, `high`, `low`, `close`, `volume`). This change simplifies the data pipeline, improves performance through vectorization, and ensures consistency across the platform.
### Package Structure
```
data/common/indicators/
├── __init__.py # Package exports
├── technical.py # TechnicalIndicators class implementation
├── result.py # IndicatorResult dataclass
└── utils.py # Utility functions for configuration
```
The module implements five core technical indicators:
@@ -20,9 +30,22 @@ The module implements five core technical indicators:
- **Vectorized Calculations**: Leverages pandas and numpy for high-speed computation.
- **Flexible `calculate` Method**: A single entry point for calculating any supported indicator by name.
- **Standardized Output**: All methods return a DataFrame containing the calculated indicator values, indexed by timestamp.
- **Modular Architecture**: Clear separation between calculation logic, result types, and utilities.
## Usage Examples
### Importing the Required Components
```python
from data.common.indicators import (
TechnicalIndicators,
IndicatorResult,
create_default_indicators_config,
validate_indicator_config
)
from data.common.data_types import OHLCVCandle
```
### Preparing the DataFrame
Before you can calculate indicators, you need a properly formatted pandas DataFrame. The `prepare_chart_data` utility is the recommended way to create one from a list of candle dictionaries.
@@ -115,15 +138,11 @@ The following details the parameters and the columns returned in the result Data
- **Parameters**: `period` (int), `std_dev` (float), `price_column` (str, default: 'close')
- **Returned Columns**: `upper_band`, `middle_band`, `lower_band`
## Integration with the TCP Platform
The refactored `TechnicalIndicators` module is now tightly integrated with the `ChartBuilder`, which handles all data preparation and calculation automatically when indicators are added to a chart. For custom analysis or strategy development, you can use the class directly as shown in the examples above. The key is to always start with a properly prepared DataFrame using `prepare_chart_data`.
## Data Structures
### IndicatorResult
Container for technical indicator calculation results.
The `IndicatorResult` class (from `data.common.indicators.result`) contains technical indicator calculation results:
```python
@dataclass
@@ -135,79 +154,50 @@ class IndicatorResult:
metadata: Optional[Dict[str, Any]] = None # Calculation metadata
```
### Configuration Format
### Configuration Management
Indicator configurations use a standardized JSON format:
```json
{
"indicator_name": {
"type": "sma|ema|rsi|macd|bollinger_bands",
"period": 20,
"price_column": "close",
// Additional parameters specific to indicator type
}
}
```
## Integration with TCP Platform
### Aggregation Strategy Compatibility
The indicators module is designed to work seamlessly with the TCP platform's aggregation strategy:
- **Right-Aligned Timestamps**: Uses `end_time` from OHLCV candles
- **Sparse Data Support**: Handles missing candles without interpolation
- **No Future Leakage**: Only processes completed candles
- **Time Boundary Respect**: Maintains proper temporal ordering
### Real-Time Processing
The module provides utilities for managing indicator configurations (from `data.common.indicators.utils`):
```python
from data.common.aggregation.realtime import RealTimeCandleProcessor
from data.common.indicators import TechnicalIndicators
# Create default configurations
config = create_default_indicators_config()
# Set up real-time processing
candle_processor = RealTimeCandleProcessor(symbol='BTC-USDT', exchange='okx')
# Validate a configuration
is_valid = validate_indicator_config({
'type': 'sma',
'period': 20,
'price_column': 'close'
})
```
### Integration with TCP Platform
The indicators module is designed to work seamlessly with the platform's components:
```python
from data.common.indicators import TechnicalIndicators
from data.common.data_types import OHLCVCandle
from components.charts.utils import prepare_chart_data
# Initialize calculator
indicators = TechnicalIndicators()
# Process incoming trades and calculate indicators
def on_new_candle(candle):
# Get recent candles for indicator calculation
recent_candles = get_recent_candles(symbol='BTC-USDT', count=50)
# Calculate indicators
sma_results = indicators.sma(recent_candles, period=20)
rsi_results = indicators.rsi(recent_candles, period=14)
# Use indicator values for trading decisions
if sma_results and rsi_results:
latest_sma = sma_results[-1].values['sma']
latest_rsi = rsi_results[-1].values['rsi']
# Trading logic here...
```
# Calculate indicators
results = indicators.calculate_multiple_indicators(df, {
'sma_20': {'type': 'sma', 'period': 20},
'rsi_14': {'type': 'rsi', 'period': 14}
})
### Database Integration
```python
from database.models import IndicatorData
# Store indicator results in database
def store_indicators(indicator_results, indicator_type):
# Access results
for indicator_name, indicator_results in results.items():
for result in indicator_results:
indicator_data = IndicatorData(
symbol=result.symbol,
timeframe=result.timeframe,
timestamp=result.timestamp,
indicator_type=indicator_type,
values=result.values,
metadata=result.metadata
)
session.add(indicator_data)
session.commit()
print(f"{indicator_name}: {result.values}")
```
## Integration with the TCP Platform
The refactored `TechnicalIndicators` module is now tightly integrated with the `ChartBuilder`, which handles all data preparation and calculation automatically when indicators are added to a chart. For custom analysis or strategy development, you can use the class directly as shown in the examples above. The key is to always start with a properly prepared DataFrame using `prepare_chart_data`.
## Performance Considerations
### Memory Usage