> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ziplime.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Пайплайны

> Расчёт кросс-секционных факторов и фильтров для выбора набора инструментов

Пайплайны — расширенный механизм расчёта кросс-секционных факторов и фильтров по множеству инструментов до запуска торговой логики. Они подходят для отбора набора инструментов, ранжирования и факторных стратегий.

Поддержка пайплайнов зависит от настройки подходящих загрузчиков данных. Стандартный путь запуска подключает ценовые данные для `EquityPricing`; для пользовательских наборов данных нужны собственные загрузчики.

## Основной принцип

1. Создайте объект `Pipeline`.
2. Подключите его в `initialize`.
3. Получите результат после инициализации — обычно в `before_trading_start`.
4. Используйте результат для выбора инструментов или целевых весов.

```python theme={null}
from ziplime.pipeline import Pipeline
from ziplime.pipeline.data import EquityPricing
from ziplime.pipeline.terms.factors import SimpleMovingAverage


def make_pipeline():
    sma_20 = SimpleMovingAverage(
        inputs=[EquityPricing.close],
        window_length=20,
    )
    return Pipeline(columns={"sma_20": sma_20})


async def initialize(context):
    context.attach_pipeline(make_pipeline(), "signals")


def before_trading_start(context, data):
    context.signals = context.pipeline_output("signals")
```

## Создание пайплайна

```python theme={null}
from ziplime.pipeline import Pipeline

pipe = Pipeline(
    columns={
        "close": EquityPricing.close.latest,
        "volume": EquityPricing.volume.latest,
    }
)
```

Столбцы можно добавить и после создания объекта:

```python theme={null}
pipe = Pipeline()
pipe.add(EquityPricing.close.latest, "close")
pipe.add(EquityPricing.volume.latest, "volume")
```

## Фильтры screen

Параметр `screen` определяет, какие инструменты попадут в результат.

```python theme={null}
from ziplime.pipeline.terms.factors import AverageDollarVolume

adv = AverageDollarVolume(window_length=20)
screen = adv.top(100)

pipe = Pipeline(
    columns={"adv": adv},
    screen=screen,
)
```

Для инструментов MOEX фактор `AverageDollarVolume` отражает средний денежный объём в валюте котировки — как правило, в рублях. Имя класса остаётся неизменным как часть API.

Фильтр также можно задать после создания пайплайна:

```python theme={null}
pipe.set_screen(screen, overwrite=True)
```

## Примеры распространённых факторов

### Последние значения OHLCV

```python theme={null}
pipe = Pipeline(columns={
    "close": EquityPricing.close.latest,
    "volume": EquityPricing.volume.latest,
})
```

### Скользящая средняя

```python theme={null}
from ziplime.pipeline.terms.factors import SimpleMovingAverage

sma_50 = SimpleMovingAverage(
    inputs=[EquityPricing.close],
    window_length=50,
)
```

### Доходность

```python theme={null}
from ziplime.pipeline.terms.factors import Returns

returns_20 = Returns(window_length=20)
```

### Средний денежный объём

```python theme={null}
from ziplime.pipeline.terms.factors import AverageDollarVolume

adv_20 = AverageDollarVolume(window_length=20)
```

## Ранжирование и фильтрация

Факторы поддерживают, в частности, следующие методы:

| Метод                                 | Значение                                                    |
| ------------------------------------- | ----------------------------------------------------------- |
| `factor.top(N)`                       | Оставить N инструментов с наибольшим значением фактора      |
| `factor.bottom(N)`                    | Оставить N инструментов с наименьшим значением фактора      |
| `factor.percentile_between(min, max)` | Оставить инструменты внутри заданного диапазона процентилей |
| `factor.rank()`                       | Ранжировать инструменты по значению                         |
| `factor.zscore()`                     | Рассчитать кросс-секционную z-оценку                        |
| `factor.demean()`                     | Вычесть кросс-секционное среднее                            |

Пример:

```python theme={null}
momentum = Returns(window_length=60)
liquid = AverageDollarVolume(window_length=20).top(500)
top_momentum = momentum.top(50, mask=liquid)

pipe = Pipeline(
    columns={"momentum": momentum},
    screen=top_momentum,
)
```

## Получение результата пайплайна

Метод `context.pipeline_output(name)` доступен после инициализации.

```python theme={null}
def before_trading_start(context, data):
    output = context.pipeline_output("signals")
    context.todays_assets = list(output.index)
```

Тип результата определяется движком пайплайна и выбранным загрузчиком. На путях, совместимых с Zipline, это pandas DataFrame с индексом по инструментам текущей сессии.

## Пользовательские факторы

Используйте `CustomFactor` для расчётов, которых нет среди встроенных факторов.

```python theme={null}
import numpy as np

from ziplime.pipeline import CustomFactor
from ziplime.pipeline.data import EquityPricing


class CloseRange(CustomFactor):
    inputs = [EquityPricing.close]
    window_length = 20

    def compute(self, today, assets, out, close):
        out[:] = np.nanmax(close, axis=0) - np.nanmin(close, axis=0)
```

Добавьте фактор в пайплайн:

```python theme={null}
pipe = Pipeline(columns={"close_range": CloseRange()})
```

## Когда использовать пайплайны

Используйте пайплайны, если:

* Нужен ежедневно ранжируемый набор инструментов.
* Один и тот же кросс-секционный фактор рассчитывается для множества инструментов.
* Ресурсоёмкую логику отбора инструментов нужно вынести из `handle_data`.

Обращайтесь напрямую к `data.current` и `data.history`, если:

* Стратегия торгует небольшим фиксированным набором инструментов.
* Сигнал прост и рассчитывается отдельно для каждого инструмента.
* Кросс-секционное ранжирование не требуется.