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

Refactor indicator management to a data-driven approach

Browse Source 
- Introduced dynamic generation of parameter fields and callback handling for indicators, enhancing modularity and maintainability.
- Updated `config_utils.py` with new utility functions to load indicator templates and generate dynamic outputs and states for parameter fields.
- Refactored `indicators.py` to utilize these utilities, streamlining the callback logic and improving user experience by reducing hardcoded elements.
- Modified `indicator_modal.py` to create parameter fields dynamically based on JSON templates, eliminating the need for manual updates when adding new indicators.
- Added documentation outlining the new data-driven architecture for indicators, improving clarity and guidance for future development.

These changes significantly enhance the flexibility and scalability of the indicator system, aligning with project goals for maintainability and performance.
This commit is contained in:
Vasily.onl
2025-06-11 19:09:52 +08:00
parent 89b071230e
commit 3e0e89b826
8 changed files with 406 additions and 249 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/decisions/ADR-005-Data-Driven-Indicators.md Normal file
View File

@@ -0,0 +1,46 @@
# ADR-005: Data-Driven Indicator System
## Status
Accepted
## Context
Previously, the technical indicator configurations, including their parameters and UI generation logic, were partially hardcoded within Python files (e.g., `dashboard/components/indicator_modal.py`, `dashboard/callbacks/indicators.py`). This approach made adding new indicators, modifying existing ones, or updating their parameter schemas a cumbersome process, requiring direct code modifications in multiple files.
The need arose for a more flexible, scalable, and maintainable system that allows for easier management and extension of technical indicators without requiring constant code deployments.
## Decision
We will refactor the technical indicator system to be fully data-driven. This involves:
1. **Centralizing Indicator Definitions**: Moving indicator metadata, default parameters, and parameter schemas into JSON template files located in `config/indicators/templates/`.
2. **Dynamic UI Generation**: The `dashboard/components/indicator_modal.py` component will dynamically read these JSON templates to generate parameter input fields for the indicator modal, eliminating hardcoded UI elements.
3. **Dynamic Callback Handling**: The `dashboard/callbacks/indicators.py` callbacks will be refactored to dynamically collect, set, and reset indicator parameters based on the schema defined in the JSON templates, removing hardcoded logic for each indicator type.
4. **Runtime Loading**: A new utility (`config/indicators/config_utils.py`) will be responsible for loading and parsing these JSON templates at runtime.
## Consequences
### Positive
- **Increased Extensibility**: Adding new indicators or modifying existing ones now primarily involves creating or updating a JSON file, significantly reducing the development overhead and time to market for new indicator support.
- **Improved Maintainability**: Centralized, data-driven configurations reduce code duplication and simplify updates, as changes are made in one place (the JSON template) rather than across multiple Python files.
- **Reduced Code Complexity**: The `indicator_modal.py` and `indicators.py` files are now more concise and generic, focusing on dynamic generation rather than specific indicator logic.
- **Enhanced Scalability**: The system can easily scale to support a large number of indicators without a proportional increase in Python code complexity.
- **Better Separation of Concerns**: UI presentation logic is decoupled from indicator definition and business logic.
### Negative
- **Initial Refactoring Effort**: Requires a significant refactoring effort to migrate existing indicators and update dependent components.
- **New File Type Introduction**: Introduces JSON files as a new configuration format, requiring developers to understand its structure.
- **Runtime Overhead (Minor)**: Small overhead for loading and parsing JSON files at application startup, though this is negligible for typical application sizes.
- **Debugging Configuration Issues**: Issues with JSON formatting or schema mismatches may require checking JSON files in addition to Python code.
## Alternatives Considered
- **Keeping Hardcoded Logic**: Rejected due to the high maintenance burden and lack of scalability.
- **Database-Driven Configuration**: Considered storing indicator configurations in a database. Rejected for initial implementation due to added complexity of database schema management, migration, and the overhead of a full CRUD API for configurations, which was deemed unnecessary for the current scope. JSON files provide a simpler, file-based persistence model that meets the immediate needs.
- **YAML/TOML Configuration**: Considered other configuration formats like YAML or TOML. JSON was chosen due to its widespread use in web contexts (Dash/Plotly integration) and native Python support.
## Decision Makers
[Your Name/Team Lead]
## Date
2024-06-12

30
docs/guides/adding-new-indicators.md
View File

@@ -202,35 +202,7 @@ SUBPLOT_REGISTRY = {
### 3. Add UI Components
Update `dashboard/components/indicator_modal.py`:
```python
def create_parameter_fields():
return html.Div([
# ... existing fields ...
html.Div([
dbc.Row([
dbc.Col([
dbc.Label("%K Period:"),
dcc.Input(
id='stochastic-k-period-input',
type='number',
value=14
)
], width=6),
dbc.Col([
dbc.Label("%D Period:"),
dcc.Input(
id='stochastic-d-period-input',
type='number',
value=3
)
], width=6),
]),
dbc.FormText("Stochastic oscillator periods")
], id='stochastic-parameters', style={'display': 'none'})
])
```
***(No longer needed - UI is dynamically generated from JSON templates)***
## Best Practices

182
docs/modules/charts/configuration.md
View File

@@ -35,11 +35,57 @@ components/charts/config/
## Indicator Definitions
### Core Classes
The indicator definitions are now primarily managed through **JSON template files** located in `config/indicators/templates/`. These JSON files define the schema, default parameters, display properties, and styling for each technical indicator. This approach allows for easy addition and modification of indicators without requiring code changes.
#### `ChartIndicatorConfig`
### Core Schema Fields (defined in JSON templates)
The main configuration class for individual indicators:
Each indicator JSON template includes the following key fields:
- **`name`**: Display name of the indicator (e.g., "Simple Moving Average")
- **`description`**: Brief explanation of the indicator.
- **`type`**: Unique identifier for the indicator (e.g., "sma", "ema"). This is used for internal mapping.
- **`display_type`**: How the indicator is rendered on the chart ("overlay" or "subplot").
- **`timeframe`**: Optional default timeframe for the indicator (can be null for chart timeframe).
- **`default_parameters`**: Default values for the indicator's calculation parameters.
- **`parameter_schema`**: Defines the type, validation rules (min/max), default values, and descriptions for each parameter.
- **`default_styling`**: Default color, line width, and other visual properties.
**Example JSON Template (`config/indicators/templates/sma_template.json`):**
```json
{
"name": "Simple Moving Average",
"description": "Simple Moving Average indicator",
"type": "sma",
"display_type": "overlay",
"timeframe": null,
"default_parameters": {
"period": 20
},
"parameter_schema": {
"period": {
"type": "int",
"min": 1,
"max": 200,
"default": 20,
"description": "Period for SMA calculation"
},
"timeframe": {
"type": "string",
"default": null,
"description": "Indicator timeframe (e.g., '1h', '4h'). Null for chart timeframe."
}
},
"default_styling": {
"color": "#007bff",
"line_width": 2
}
}
```
### `ChartIndicatorConfig` (Python representation)
The `ChartIndicatorConfig` Python dataclass in `components/charts/config/indicator_defs.py` serves as the runtime representation of an indicator's configuration, parsed from the JSON templates.
```python
@dataclass
@@ -56,7 +102,9 @@ class ChartIndicatorConfig:
subplot_height_ratio: float = 0.3 # For subplot indicators
```
#### Enums
### Enums (for internal type safety)
Enums like `IndicatorType`, `DisplayType`, `LineStyle` are still used internally for type safety and consistent value representation within the Python codebase.
**IndicatorType**
```python
@@ -67,6 +115,7 @@ class IndicatorType(str, Enum):
MACD = "macd"
BOLLINGER_BANDS = "bollinger_bands"
VOLUME = "volume"
# ... new indicator types should be added here for internal consistency
```
**DisplayType**
@@ -86,7 +135,19 @@ class LineStyle(str, Enum):
DASH_DOT = "dashdot"
```
### Schema Validation
**PriceColumn**
```python
class PriceColumn(str, Enum):
OPEN = "open"
HIGH = "high"
LOW = "low"
CLOSE = "close"
VOLUME = "volume"
```
### Schema Validation (driven by JSON templates)
The validation system now primarily reads parameter schemas from the JSON templates. The `IndicatorParameterSchema` and `IndicatorSchema` dataclasses are used for internal representation when parsing and validating these JSON definitions.
#### `IndicatorParameterSchema`
@@ -119,39 +180,9 @@ class IndicatorSchema:
description: str = ""
```
### Schema Definitions
### Schema Definitions (now loaded dynamically)
The system includes complete schemas for all supported indicators:
```python
INDICATOR_SCHEMAS = {
IndicatorType.SMA: IndicatorSchema(
indicator_type=IndicatorType.SMA,
display_type=DisplayType.OVERLAY,
parameters=[
IndicatorParameterSchema(
name="period",
type=int,
min_value=1,
max_value=200,
default_value=20,
description="Number of periods for the moving average"
),
IndicatorParameterSchema(
name="price_column",
type=str,
required=False,
default_value="close",
valid_values=["open", "high", "low", "close"],
description="Price column to use for calculation"
)
],
description="Simple Moving Average - arithmetic mean of prices",
calculation_description="Sum of closing prices divided by period"
),
# ... more schemas
}
```
The `INDICATOR_SCHEMAS` dictionary is now populated dynamically at runtime by loading and parsing the JSON template files. Manual definitions in `indicator_defs.py` are deprecated.
### Utility Functions
@@ -636,33 +667,58 @@ if performance_issues:
### Adding New Indicators
1. **Define Indicator Type**
```python
# Add to IndicatorType enum
class IndicatorType(str, Enum):
# ... existing types
STOCHASTIC = "stochastic"
```
- Add to `IndicatorType` enum (if not already present)
2. **Create Schema**
```python
# Add to INDICATOR_SCHEMAS
INDICATOR_SCHEMAS[IndicatorType.STOCHASTIC] = IndicatorSchema(
indicator_type=IndicatorType.STOCHASTIC,
display_type=DisplayType.SUBPLOT,
parameters=[
IndicatorParameterSchema(
name="k_period",
type=int,
min_value=1,
max_value=100,
default_value=14
),
# ... more parameters
],
description="Stochastic Oscillator",
calculation_description="Momentum indicator comparing closing price to price range"
)
```
2. **Create JSON Template**
- Create a new JSON file in `config/indicators/templates/` (e.g., `stochastic_template.json`)
- Define the indicator's name, type, display type, default parameters, parameter schema, and default styling.
- **Example (`stochastic_template.json`):**
```json
{
"name": "Stochastic Oscillator",
"description": "Stochastic momentum oscillator indicator",
"type": "stochastic",
"display_type": "subplot",
"timeframe": null,
"default_parameters": {
"k_period": 14,
"d_period": 3,
"smooth_k": 1
},
"parameter_schema": {
"k_period": {
"type": "int",
"min": 2,
"max": 50,
"default": 14,
"description": "Period for %K calculation"
},
"d_period": {
"type": "int",
"min": 1,
"max": 20,
"default": 3,
"description": "Period for %D (moving average of %K)"
},
"smooth_k": {
"type": "int",
"min": 1,
"max": 10,
"default": 1,
"description": "Smoothing factor for %K"
},
"timeframe": {
"type": "string",
"default": null,
"description": "Indicator timeframe (e.g., '1h', '4h'). Null for chart timeframe."
}
},
"default_styling": {
"color": "#e83e8c",
"line_width": 2
}
}
```
3. **Create Default Presets**
```python

4
docs/modules/charts/indicators.md
View File

@@ -89,7 +89,7 @@ These indicators are displayed in separate panels:
- Name: Custom name for the indicator
- Type: Select from available indicator types
- Description: Optional description
3. **Set Parameters**: Type-specific parameters appear dynamically
3. **Set Parameters**: Type-specific parameters appear dynamically (generated from JSON templates)
4. **Customize Styling**:
- Color: Hex color code
- Line Width: 1-5 pixels
@@ -169,7 +169,7 @@ class UserIndicator:
description: str # User description
type: str # Indicator type (sma, ema, etc.)
display_type: str # "overlay" or "subplot"
parameters: Dict[str, Any] # Type-specific parameters
parameters: Dict[str, Any] # Type-specific parameters, dynamically loaded from JSON templates
styling: IndicatorStyling # Appearance settings
visible: bool = True # Default visibility
created_date: datetime # Creation timestamp

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

@@ -304,12 +304,13 @@ for timestamp, row in result_df.iterrows():
## Contributing
When adding new indicators:
1. Create a new class in `implementations/`
2. Inherit from `BaseIndicator`
3. Implement the `calculate` method to return a DataFrame
4. Ensure proper warm-up periods
5. Add comprehensive tests
6. Update documentation
1. Create a new class in `implementations/`.
2. Inherit from `BaseIndicator`.
3. Implement the `calculate` method to return a DataFrame.
4. Ensure proper warm-up periods.
5. Add comprehensive tests.
6. Create a corresponding **JSON template file** in `config/indicators/templates/` to define its parameters, display properties, and styling for UI integration.
7. Update documentation in `docs/guides/adding-new-indicators.md`.
See [Adding New Indicators](./adding-new-indicators.md) for detailed instructions.