# Глубокое погружение: Пайплайн анализатора зон

> 💡 **Для кого это руководство?**
>
> Этот документ предназначен для разработчиков и аналитиков, которые хотят понять **внутреннюю логику и механику** универсального пайплайна `analyze_zones`. Если вы ищете справочник по функциям и параметрам, обратитесь к [API документации](../api/analysis/zones.md).

## 1. Главная идея: Универсальность и Контекст

Основная цель пайплайна `analyze_zones` — предоставить **универсальный** инструмент для исследования рыночных "зон". Зона — это не просто отрезок времени, а период, выделенный по определенному правилу, основанному на поведении технического индикатора.

Ключевая инновация — **контекст**. Каждая найденная зона "знает", как она была обнаружена: какой индикатор использовался, по какой стратегии (пересечение нуля, выход из зоны перекупленности и т.д.) и с какими параметрами. Это позволяет анализировать и визуализировать зоны от **любого индикатора** (MACD, RSI, Stochastic или даже вашего собственного) единым образом, без необходимости переписывать код.

---

## 2. Пошаговый процесс анализа

Пайплайн представляет собой "конструктор" (builder), где вы по шагам настраиваете каждый аспект анализа.

#### Шаг 1: Инициализация (`analyze_zones(df)`)

-   **Что происходит?** Вы передаете в пайплайн исходные данные — DataFrame с колонками `open`, `high`, `low`, `close`, `volume`.
-   **Результат:** Создается объект-конструктор `ZoneAnalysisBuilder`, который готов к дальнейшей настройке.

#### Шаг 2: Расчет индикатора (`.with_indicator(...)`)

-   **Что происходит?** На этом шаге вы "сообщаете" пайплайну, какой индикатор использовать. Это может быть:
    -   **Встроенный индикатор**: Например, `.with_indicator('custom', 'macd', ...)` рассчитает MACD.
    -   **Индикатор из библиотеки `pandas-ta`**: Например, `.with_indicator('pandas_ta', 'rsi', length=14)` рассчитает RSI.
    -   **Уже существующий индикатор**: Если в вашем DataFrame уже есть колонка с индикатором, этот шаг можно пропустить.
-   **Результат:** В DataFrame добавляются новые колонки с рассчитанными значениями индикатора (например, `macd_hist`, `RSI_14`).

#### Шаг 3: Детекция зон (`.detect_zones(...)`)

-   **Что происходит?** Это ядро процесса. Здесь пайплайн ищет на графике индикатора отрезки, соответствующие заданной **стратегии детекции**. Основные стратегии:
    -   `'zero_crossing'`: Находит зоны, где индикатор-осциллятор (например, гистограмма MACD) находится выше или ниже нуля.
    -   `'threshold'`: Находит зоны, где индикатор (например, RSI) выходит за пределы заданных порогов (например, выше 70 или ниже 30).
    -   `'line_crossing'`: Находит зоны между пересечениями двух линий индикатора (например, основной и сигнальной линий Stochastic).
-   **Результат:** Создается предварительный список зон. Каждая зона — это пока просто объект с временем начала, временем конца и типом (`bull`/`bear`).

#### Шаг 4: Глубокий анализ характеристик

Это самый насыщенный этап анализа, состоящий из трех логических частей: подключение стратегий, запуск анализа и сборка результата.

##### 4.1. Подключение стратегий анализа (`.with_strategies(...)`)

На этом шаге вы сообщаете пайплайну, какие именно характеристики (метрики) нужно извлечь из каждой зоны. Это делается путем передачи строковых идентификаторов для каждого типа анализа.

-   **Что происходит?** Вы выбираете и настраиваете "анализаторы", которые будут применяться к каждой зоне.
-   **Доступные стратегии:**
    -   **Анализ внутренних колебаний (`swing`):**
        -   `swing='find_peaks'`: (Рекомендуемый) Поиск пиков и впадин на основе `scipy.signal.find_peaks`.
        -   `swing='pivot_points'`: Классические точки разворота.
        -   `swing='zigzag'`: Поиск экстремумов с помощью индикатора ZigZag.
    -   **Анализ формы (`shape`):**
        -   `shape='statistical'`: Расчет статистических моментов (асимметрия, эксцесс) для формы индикатора.
    -   **Анализ дивергенций (`divergence`):**
        -   `divergence='classic'`: Поиск классических бычьих и медвежьих дивергенций.
    -   **Анализ волатильности (`volatility`):**
        -   `volatility='combined'`: Расчет составного индекса волатильности внутри зоны.
    -   **Анализ объема (`volume`):**
        -   `volume='standard'`: Расчет метрик, связанных с объемом.

##### 4.2. Запуск анализа и доп. процессов (`.analyze(...)`)

Этот метод запускает извлечение всех метрик, настроенных на предыдущем шаге. Кроме того, он может запускать дополнительные высокоуровневые аналитические процессы.

-   **Что происходит?**
    1.  Пайплайн проходит по каждой зоне и применяет к ней все стратегии, указанные в `.with_strategies()`. Результаты сохраняются в словарь `zone.features`.
    2.  **Кластеризация:** Если передан аргумент `clustering=True`, запускается алгоритм кластеризации (например, KMeans) для группировки похожих зон. Результаты доступны в `result.clustering`.
    3.  **Статистические тесты:** Пайплайн **автоматически** запускает набор тестов гипотез (например, t-тест для сравнения доходностей бычьих и медвежьих зон). Результаты доступны в `result.hypothesis_tests`.

##### 4.3. Ключевые метрики (Features), генерируемые стратегиями

Главный результат этого шага — наполнение словаря `features` для каждой зоны. Ниже приведены примеры ключевых метрик, которые генерируют разные стратегии.

| Стратегия (`.with_strategies(...)`) | Ключевая метрика в `zone.features` | Описание |
| :--- | :--- | :--- |
| `swing='find_peaks'` | `num_peaks`, `num_troughs` | Количество пиков и впадин внутри зоны. |
| | `peak_time_ratio` | Положение главного пика в зоне (0.0 - начало, 1.0 - конец). |
| | `drawdown_from_peak` | Максимальная просадка цены от пика внутри зоны. |
| `divergence='classic'` | `has_classic_divergence` | `True`, если найдена классическая дивергенция. |
| `volatility='combined'`| `volatility_score` | Составная оценка волатильности в зоне (например, от 0 до 10). |
| `volume='standard'` | `volume_indicator_corr` | Корреляция между объемом и индикатором в зоне. |
| `shape='statistical'` | `skewness`, `kurtosis` | Асимметрия и эксцесс распределения значений индикатора. |

#### Шаг 5: Сборка (`.build()`)

-   **Что происходит?** Финальный вызов, который запускает весь настроенный конвейер в правильном порядке: `.with_indicator` -> `.detect_zones` -> `.analyze`.
-   **Результат:** Возвращается единый, полностью готовый объект `ZoneAnalysisResult`.

---
#### Пример полного пайплайна

Вот как выглядит полный цикл анализа в коде, объединяющий все шаги:

```python
# Полный пайплайн от данных до результата
result = (
    analyze_zones(df)
    .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', shape='statistical', divergence='classic')
    .analyze(clustering=True, n_clusters=3)
    .build()
)

# Пример доступа к извлеченным метрикам
first_zone_features = result.zones[0].features
print(f"Положение пика в первой зоне: {first_zone_features.get('peak_time_ratio')}")

# Пример доступа к результатам тестов гипотез
if result.hypothesis_tests:
    print(result.hypothesis_tests.results)
```

---

## 3. Итоговая информация (объект `ZoneAnalysisResult`)

В результате вы получаете не просто набор цифр, а структурированный объект, готовый к дальнейшему исследованию и визуализации.

-   **`result.zones`**: Это список объектов `ZoneInfo`. Каждый объект `ZoneInfo` — это исчерпывающее описание одной зоны:
    -   `zone_id`, `type`, `start_time`, `end_time`: Базовая информация.
    -   **`features`**: Словарь со всеми численными метриками, извлеченными на Шаге 4 (например, `{'duration': 15, 'price_return': 0.012, 'num_peaks': 3, ...}`). **Это и есть главные данные для анализа.**
    -   **`indicator_context`**: Словарь, описывающий, как зона была найдена (например, `{'detection_indicator': 'macd_hist', 'detection_strategy': 'zero_crossing'}`). Это ключ к универсальности.

-   **`result.statistics`**: Агрегированная статистика по всем найденным зонам. Например, средняя длительность бычьих зон, медианное изменение цены в медвежьих зонах, распределение зон по часам и т.д.

-   **`result.clustering`**: Если была включена кластеризация, здесь хранятся ее результаты (например, какому кластеру принадлежит каждая зона).

-   **`result.visualize(...)`**: Встроенный метод, который использует всю собранную информацию (особенно `indicator_context`) для автоматического построения [графиков визуализации зон](../api/visualization/zones.md).

### Итог

Пайплайн `analyze_zones` — это конвейер, который превращает сырые ценовые данные в богатый, структурированный набор данных. Он не просто находит отрезки на графике, а **количественно описывает** их внутреннюю структуру (через `features`) и **сохраняет контекст** их обнаружения (через `indicator_context`), что делает результаты универсальными, воспроизводимыми и готовыми к немедленной визуализации и дальнейшему анализу.

---

### Шаг 6: Статистическая верификация

Поиск и описание зон — это первый шаг анализа. Однако, чтобы убедиться, что найденные закономерности (например, повышенная доходность в бычьих зонах) не являются случайностью, их необходимо проверить с помощью статистических тестов.

**Для подробного изучения методов валидации и проверки гипотез обратитесь к нашему руководству:**

**➡️ [Руководство по рабочему процессу статистического анализа](./statistical_analysis_workflow.md)**

---

## 🔗 См. также

- **[Технический справочник API (analysis.zones)](../api/analysis/zones.md)**: Полный список классов, методов и параметров.
- **[Документация по визуализации](../api/visualization/zones.md)**: Как визуализировать полученные зоны.
- **[Руководство пользователя по анализу зон](../user_guide/zone_analysis.md)**: Практические примеры использования.
