Примеры использования BQuant

📚 Обзор

Примеры использования BQuant демонстрируют различные сценарии применения библиотеки от простых до сложных.

🗂️ Категории примеров

🚀 Примеры универсального анализа зон

01_basic_indicators.py — ОСНОВЫ ИНДИКАТОРОВ (314 строк)
- IndicatorFactory и LibraryManager: базовые SMA, RSI, MACD, Bollinger Bands
- Создание данных: create_sample_ohlcv_data() без внешних источников
- Авто-загрузка библиотек: LibraryManager.load_all_libraries() и интеграция с pandas-ta
02a_universal_zones.py — ГЛАВНЫЙ ТУТОРИАЛ (693 строки)
- Универсальный API: MACD, RSI, AO, MA crossover, Stochastic, кастомные индикаторы и preloaded-зоны
- Отсутствие дублирования: один pipeline для всех стратегий детекции
- Кэширование и сохранение: pickle, JSON и parquet для результатов анализа
- Модульный запуск: отдельные функции для подготовки, анализа и визуализации
02_macd_zone_analysis.py — РУКОВОДСТВО ПО МИГРАЦИИ (406 строк)
Legacy vs Universal (сравнение): пошаговое сопоставление старого и нового API
Предупреждения об устаревании (Deprecation Warnings): демонстрация предупреждений и путей миграции
Бенчмарк производительности: измерение времени и памяти для обоих подходов
- Несколько стратегий: zero_crossing, line_crossing, комбинированные правила и профили fallback

📈 Примеры продвинутых возможностей

03_data_processing.py — ДЕМОНСТРАЦИЯ PIPELINE ДАННЫХ (510 строк)
ETL-конвейер: очистка, агрегация и нормализация рыночных данных
Инженерия признаков (feature engineering): генерация признаков для последующего анализа зон
- Отчётность: структурированный вывод метрик и логирование прогресса
04_comprehensive_analysis.py — ПОЛНЫЙ PIPELINE (301 строк)
- UniversalZoneAnalyzer: конфигурация через ZoneDetectionRegistry
- Смешанные режимы рынка: демонстрация тренда, коррекции и боковика
- Полный цикл: от подготовки данных до сохранения результатов анализа
05_strategies_demo.py — ГЛУБОКОЕ ПОГРУЖЕНИЕ В СТРАТЕГИИ (401 строк)
Колебательные и дивергенционные стратегии: FindPeaks, PivotPoints, ZigZag, классические дивергенции
.with_strategies() API: комбинирование нескольких стратегий в одном пайплайне
zone.features: доступ к расширенным метрикам, устойчивым fallback-аналитикам и печать симметрии длительности
06_regression_demo.py — РЕГРЕССИОННЫЙ АНАЛИЗ (345 строк)
- Статистическое моделирование: регрессия по метрикам зон и контроль стабильности R²
- Подготовка признаков: нормализация метрик зон, train/test split и оценка
- Валидация: сравнение моделей, коэффициентов и чувствительности к индикаторам
07_validation_demo.py — ФРЕЙМВОРК ВАЛИДАЦИИ (536 строк)
Кросс-валидация (cross-validation): проверка стабильности стратегий на нескольких срезах
Метрики качества: устойчивость R², permutation test и контроль ресурсоёмкости
Стресс-тесты: анализ поведения при разных объёмах данных и профили нагрузки

🔬 Исследовательские ноутбуки

03_zones_universal.py — Глубокий разбор универсального анализа зон (412 строк) (см. исходный код)
03_analysis_new_features.py — Тестирование новых аналитических возможностей (см. исходный код)

🎯 Быстрый старт с примерами

1. Универсальный анализ зон

# examples/02a_universal_zones.py
import bquant as bq
from bquant.data.samples import get_sample_data
from bquant.analysis.zones import analyze_zones

# Загружаем данные
data = get_sample_data('tv_xauusd_1h')

# Universal Pipeline - любой индикатор
result = (
    analyze_zones(data)
    .with_indicator('pandas_ta', 'rsi', length=14)
    .detect_zones('threshold', indicator_col='RSI_14',  # колонка создаётся pandas-ta
                  upper_threshold=70, lower_threshold=30)
    .analyze(clustering=True)
    .build()
)

# Выводим результаты
print(f"Найдено зон: {len(result.zones)}")
if not result.zones:
    print("⚠️ RSI на текущем датасете не пересёк пороги 70/30 — зон может не быть.")
print(f"Статистика: {result.statistics}")

2. Руководство по миграции — Legacy vs New API

# examples/02_macd_zone_analysis.py

# ⚠️ УСТАРЕВШИЙ СПОСОБ (DEPRECATED)
from bquant.indicators import MACDZoneAnalyzer
analyzer = MACDZoneAnalyzer()
result = analyzer.analyze_complete(data)

# ✅ Новый способ: Universal Pipeline
from bquant.analysis.zones import analyze_zones
result = (
    analyze_zones(data)
    .with_indicator('custom', 'macd', fast_period=12, slow_period=26, signal_period=9)
    .detect_zones('zero_crossing', indicator_col='macd_hist')
    .analyze(clustering=True)
    .build()
)

3. Продвинутые возможности — стратегии и анализ

# examples/05_strategies_demo.py
from bquant.analysis.zones import analyze_zones
from bquant.data.samples import get_sample_data

data = get_sample_data('tv_xauusd_1h')

# Продвинутые стратегии
result = (
    analyze_zones(data)
    .with_indicator('custom', 'macd', fast_period=12, slow_period=26, signal_period=9)
    .detect_zones('zero_crossing', indicator_col='macd_hist')
    .with_strategies(
        swing='find_peaks',      # Анализ swing-движений
        divergence='classic',    # Обнаружение дивергенций
        volume='standard',       # Анализ объёма
        volatility='combined'    # Анализ волатильности
    )
    .analyze(clustering=True)
    .build()
)

# Hypothesis tests автоматически в pipeline
if result.hypothesis_tests:
    for test_name, test_result in result.hypothesis_tests.results.items():
        p_value = test_result.get('p_value')
        if p_value is not None:
            print(f"{test_name}: p={p_value:.4f}")
        else:
            print(f"{test_name}: {test_result}")

🗺️ Навигация по примерам

🚀 Quick Start

Basic Indicators (см. исходный код) — стартовая демонстрация IndicatorFactory
Universal Zones (см. исходный код) — НАЧНИТЕ ЗДЕСЬ: любой индикатор за 3 строки

📚 Маршрут изучения

Migration Guide (02_macd_zone_analysis.py) — переход с deprecated API (см. исходный код)
Strategies Deep Dive (05_strategies_demo.py) — все типы стратегий (см. исходный код)
Regression Analysis (06_regression_demo.py) — статистическое моделирование (см. исходный код)
Validation Framework (07_validation_demo.py) — проверка качества (см. исходный код)

🔗 Перекрёстные ссылки

API Documentation: Pipeline API
Strategy Reference: Detection Strategies
Visualization: Zone Visualization
Developer Guide: Architecture Patterns

📊 Структура каждого примера

📖 Заголовок и описание

"""
Пример: Анализ MACD с зонами

Этот пример демонстрирует:
- Загрузку sample данных
- Создание анализатора MACD
- Выполнение полного анализа
- Визуализацию результатов

Автор: BQuant Team
Дата: 2024
"""

🔧 Импорты и настройка

import bquant as bq
from bquant.data.samples import get_sample_data
from bquant.indicators import MACDZoneAnalyzer
from bquant.visualization import FinancialCharts

# Настройка логирования
import logging
import plotly.io as pio

logging.basicConfig(level=logging.INFO)
pio.renderers.default = "json"  # безопасный renderer для headless-среды

💻 Основной код

def main():
    """Основная функция примера"""
    
    # 1. Загрузка данных
    print("Загружаем данные...")
    data = get_sample_data('tv_xauusd_1h')
    
    # 2. Анализ
    print("Выполняем анализ...")
    analyzer = MACDZoneAnalyzer()
    result = analyzer.analyze_complete(data)
    
    # 3. Результаты
    print("Результаты анализа:")
    print(f"  - Зон найдено: {len(result.zones)}")
    print(f"  - Статистика: {result.statistics}")
    
    # 4. Визуализация
    print("Создаем визуализацию...")
    charts = FinancialCharts()
    try:
        fig = charts.plot_macd_with_zones(data, result.zones)
        fig.show()
    except Exception as exc:
        print(f"⚠️ Визуализация недоступна: {exc}")

if __name__ == "__main__":
    main()

📋 Документация

Описание - Что делает пример
Требования - Необходимые зависимости
Запуск - Как запустить пример
Результаты - Что ожидать на выходе

📏 Example Quality Standards

Self-contained

Независимость - каждый пример работает без внешних зависимостей
Sample данные - использование встроенных sample данных
Полный код - все необходимые импорты и функции включены

Well-documented

Подробные комментарии - объяснение каждого шага
Docstrings - документация для всех функций
Примеры вывода - ожидаемые результаты

Error-handled

Graceful degradation - обработка отсутствующих опциональных компонентов
Try/except блоки - обработка возможных ошибок
Информативные сообщения - понятные сообщения об ошибках

Performance-aware

Демонстрация кэширования - показ возможностей оптимизации
Время выполнения - измерение производительности
Memory usage - контроль использования памяти

🔗 Integration with Documentation

API Cross-links

Ссылки на API - каждый пример ссылается на соответствующие разделы API
Code examples - примеры кода в документации соответствуют примерам
Parameter references - ссылки на параметры и их значения

Tutorial Integration

Связь с учебными материалами - примеры интегрированы с tutorials
Learning path - логическая последовательность изучения
Progressive complexity - от простого к сложному

Developer Resources

Архитектурные принципы - ссылки на design patterns
Extension points - показ возможностей расширения
Best practices - демонстрация лучших практик

🚀 Как запускать примеры

1. Клонирование репозитория

git clone https://github.com/bquant-team/bquant.git
cd bquant

2. Установка зависимостей

pip install -e .

3. Запуск примера

# Базовый пример
python examples/01_basic_indicators.py

# Продвинутый пример
python examples/02a_universal_zones.py

# С параметрами
python examples/06_regression_demo.py

4. В Jupyter Notebook

# Запускаем пример в интерактивном режиме
from pathlib import Path
import runpy

example_path = Path("examples/02a_universal_zones.py")
try:
    runpy.run_path(example_path, run_name="__main__")
except (TypeError, LookupError, RuntimeError, ValueError) as exc:
    print("⚠️ Скрипт требует дополнительные аргументы или опциональные библиотеки (pandas-ta/talib):", exc)

💡 Советы по использованию примеров

🎯 Для изучения

Начните с basic/ - Освойте базовые концепции
Изучайте код - Читайте комментарии и docstrings
Экспериментируйте - Изменяйте параметры и наблюдайте результаты
Задавайте вопросы - Если что-то непонятно

🔧 Для разработки

Используйте как шаблоны - Адаптируйте под свои нужды
Изучайте паттерны - Обратите внимание на структуру кода
Тестируйте изменения - Проверяйте работу после модификаций
Документируйте - Добавляйте комментарии к своим изменениям

🚀 Для продакшена

Адаптируйте под данные - Замените sample данные на реальные
Добавьте обработку ошибок - Используйте try/except блоки
Оптимизируйте производительность - Примените техники из performance/
Настройте логирование - Добавьте информативные логи

🔗 Связанные разделы

User Guide - Руководство пользователя
API Reference - Справочник API
Tutorials - Обучающие материалы
Developer Guide - Для разработчиков

🤝 Вклад в примеры

Добавление нового примера

Создайте файл в соответствующей папке
Добавьте документацию - описание, требования, запуск
Протестируйте - убедитесь что пример работает
Создайте PR - предложите изменения

Структура нового примера

"""
Название: Краткое описание

Подробное описание что делает пример и как его использовать.

Требования:
- bquant
- pandas
- matplotlib

Запуск:
python examples/category/example_name.py

Автор: Ваше имя
Дата: YYYY-MM-DD
"""

import bquant as bq
# ... остальные импорты

def main():
    """Основная функция"""
    pass

if __name__ == "__main__":
    main()

Начать изучение: 02a_universal_zones.py (см. исходный код) 🚀