Tutorial: Preloaded зоны (Пример 3 + Сценарий 9)

🎯 Цели

  • Воспроизвести Пример 3: PRELOADED индикатор + зоны (см. документацию)

  • Повторить модульный Сценарий 9: работа с PRELOADED зонами (внешние данные)

  • Разобрать формат входного CSV и лучшие практики интеграции

🔧 Предварительные требования

  • Готовый CSV/Excel с разметкой зон эксперта или внешней системы

  • OHLCV-данные, синхронизированные по времени (используем sample tv_xauusd_1h)

📥 Формат входных данных

PreloadedZonesDetection ожидает минимум четыре колонки.

Колонка

Тип

Описание

zone_id

int

Уникальный идентификатор

type

str

Тип зоны (bull, bear, support, resistance, …)

start_time

datetime

Начало зоны (ISO 8601)

end_time

datetime

Конец зоны (ISO 8601)

Дополнительно можно добавить indicator, comment и любые метаданные — они попадут в ZoneInfo.data и indicator_context.

Пример CSV

zone_id,type,start_time,end_time,indicator
0,bull,2025-01-01T00:00:00,2025-01-01T06:00:00,external_model
1,bear,2025-01-02T12:00:00,2025-01-02T18:00:00,manual_markup

🛠️ Шаг 1. Быстрый pipeline с preloaded зонами

Воспользуемся fluent builder: индикатор внутри pipeline не нужен, потому что зоны уже размечены.

from bquant.data.samples import get_sample_data
from bquant.analysis.zones import analyze_zones

df = get_sample_data('tv_xauusd_1h')

preloaded_result = (
    analyze_zones(df)
    .detect_zones('preloaded', zones_data='expert_zones.csv', time_tolerance='5min', min_duration=2)
    .analyze(clustering=False)
    .build()
)

print(f"Loaded zones: {len(preloaded_result.zones)}")
print(preloaded_result.zones[0].indicator_context['source'])  # 'external'

♻️ Шаг 2. Модульный сценарий (zomodul #9)

Для повторного использования сохраним зоны в pickle и сравним с автоматической детекцией, как показано в zomodul.md.

import pickle
from bquant.analysis.zones.detection import ZoneDetectionRegistry, ZoneDetectionConfig
from bquant.analysis.zones.detection.preloaded import load_preloaded_zones
from bquant.indicators import IndicatorFactory

# 1. Загрузка preloaded зон
zones = load_preloaded_zones('expert_zones.csv', df, time_tolerance='5min', min_duration=2)

with open('expert_zones.pkl', 'wb') as f:
    pickle.dump(zones, f)

# 2. Рассчитываем MACD для автоматической стратегии
indicator = IndicatorFactory.create('custom', 'macd', fast=12, slow=26, signal=9)
macd_result = indicator.calculate(df)
df_with_macd = df.join(macd_result.data)

# 3. Анализ эксперта vs автоматической детекции
from bquant.analysis.zones import UniversalZoneAnalyzer
analyzer = UniversalZoneAnalyzer()
expert_analysis = analyzer.analyze_zones(zones, df)

auto_detector = ZoneDetectionRegistry.get('zero_crossing')
auto_config = ZoneDetectionConfig(strategy_name='zero_crossing', rules={'indicator_col': 'macd_hist'}, min_duration=2)
auto_zones = auto_detector.detect_zones(df_with_macd, auto_config)
auto_analysis = analyzer.analyze_zones(auto_zones, df_with_macd)

comparison = {
    'expert': {'zones': len(zones), 'win_rate': expert_analysis.statistics.get('win_rate')},
    'automatic': {'zones': len(auto_zones), 'win_rate': auto_analysis.statistics.get('win_rate')}
}
print(comparison)

📊 Визуализация и контроль качества

preloaded_result.visualize('overview', title='Expert Zones vs Price').show()
preloaded_result.visualize('statistics').show()

  • Используйте visualize('detail', zone_id=...), чтобы убедиться, что временные окна совпадают.

  • Если зона не отображается, проверьте time_tolerance и наличие строк в ZoneInfo.data.

✅ Лучшие практики

  1. Валидируйте вход — проверяйте missing колонки перед запуском (ValueError при отсутствии).

  2. Сохраняйте оригинал — держите исходный CSV рядом с pickle, чтобы отслеживать ревизии разметки.

  3. Временной допуск — увеличивайте time_tolerance для разреженных данных или нестандартных сессий.

  4. Метаданные — добавляйте столбцы с параметрами модели, чтобы в indicator_context сохранить источник.

  5. Сравнение стратегий — комбинируйте анализ эксперта с автоматическими зонами для контроля качества, как в коде выше.

🚀 Что дальше

  • Автоматизируйте загрузку из S3/БД, передавая pd.DataFrame вместо пути.

  • Используйте ZoneFeaturesAnalyzer для метрик качества preloaded зон.

  • Создайте CI-проверку, сравнивающую win-rate экспертов и автоматических стратегий.