Миграция с классического Zipline

Ziplime сохраняет событийную модель стратегий классического Zipline, но не является его полной заменой без изменений в коде. Основные различия — асинхронные функции стратегии, DataFrame библиотеки Polars, явные стили исполнения и механизм запуска с пакетами данных и сервисами Ziplime от Финама. Используйте эту страницу при переносе старого алгоритма Zipline в файл алгоритма Ziplime.

Что осталось знакомым

Основная структура стратегии не изменилась:

def initialize(context):
    ...


def handle_data(context, data):
    ...

В Ziplime основные функции становятся асинхронными:

async def initialize(context):
    ...


async def handle_data(context, data):
    ...

Сохраняется и общая модель работы:

Постоянное состояние стратегии хранится в context.
Торговая логика для каждого бара размещается в handle_data.
Для периодической ребалансировки используется schedule_function.
Пользовательские метрики записываются через record.
Для ребалансировки применяются методы целевых заявок.

Краткая таблица преобразований

Шаблон классического Zipline	Шаблон Ziplime
`from zipline.api import symbol`	Внутри `initialize` предпочтителен `await context.symbol(...)`.
`asset = symbol("SBER")`	`asset = await context.symbol("SBER")`
`symbols("SBER", "GAZP")`	`[await context.symbol(s) for s in ["SBER", "GAZP"]]`
`data.current(asset, "close")`	`(await data.current(assets=[asset], fields=["close"]))["close"][0]`
`data.history(asset, "close", 20, "1d")`	`await data.history(assets=[asset], fields=["close"], bar_count=20)`
`order(asset, 100)`	`await context.order(asset, 100, style=MarketOrder())`
`order_target_percent(asset, 0.5)`	`await context.order_target_percent(asset, 0.5, style=MarketOrder())`
Результаты доступа к данным в pandas	DataFrame Polars из `data.current` и `data.history`.
Синхронная `handle_data`	`async def handle_data(...)` и `await` перед асинхронными вызовами API.
`run_algorithm(...)` с данными в памяти	`run_simulation(...)` с загруженными пакетами и сервисами Ziplime.

Импорты

Алгоритмы классического Zipline часто импортируют множество функций API:

from zipline.api import (
    symbol,
    order_target_percent,
    record,
    schedule_function,
    date_rules,
    time_rules,
)

В Ziplime предпочтительнее напрямую вызывать методы context и импортировать только вспомогательные классы:

from ziplime.finance.execution import MarketOrder
from ziplime.utils.events import date_rules, time_rules

Пространство имён ziplime.api в стиле Zipline сохранено для совместимости, но прямые вызовы context легче читать в асинхронном коде:

asset = await context.symbol("SBER")
await context.order_target_percent(asset, 0.25, style=MarketOrder())
context.record(weight=0.25)

Функции жизненного цикла

`initialize`

Классический Zipline:

def initialize(context):
    context.asset = symbol("SBER")

Ziplime:

async def initialize(context):
    context.asset = await context.symbol("SBER")

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

`handle_data`

Классический Zipline:

def handle_data(context, data):
    price = data.current(context.asset, "close")
    if price > 300:
        order_target_percent(context.asset, 1.0)

Ziplime:

from ziplime.finance.execution import MarketOrder


async def handle_data(context, data):
    current = await data.current(assets=[context.asset], fields=["close"])
    price = current["close"][0]

    if price > 300:
        await context.order_target_percent(
            context.asset,
            1.0,
            style=MarketOrder(),
        )

`before_trading_start`

В классическом Zipline before_trading_start была синхронной. Сейчас Ziplime вызывает её так же.

def before_trading_start(context, data):
    context.traded_today = False

В текущей версии Ziplime не определяйте эту функцию через async def и не размещайте в ней заявки.

`analyze`

Классический Zipline обычно передавал в analyze DataFrame с результатами. Ziplime также синхронно вызывает analyze с итоговой таблицей результатов.

def analyze(context, perf):
    print(perf.tail())

Различия в работе с рыночными данными

Классический Zipline поддерживал вызовы, возвращающие скалярные значения:

price = data.current(asset, "close")
history = data.history(asset, "close", 20, "1d")

Ziplime ожидает списки и возвращает DataFrame Polars:

current = await data.current(
    assets=[asset],
    fields=["close", "volume"],
)

price = current["close"][0]
volume = current["volume"][0]

Исторические окна тоже запрашиваются асинхронно:

history = await data.history(
    assets=[asset],
    fields=["close"],
    bar_count=20,
)

mean_close = history["close"].mean()

Если старая стратегия использует операции pandas, преобразуйте результат Ziplime явно:

pandas_history = history.to_pandas()

Для нового кода предпочтительнее выражения Polars.

Различия в работе с заявками

Классический Zipline часто допускал такие вызовы:

order(asset, 100)
order_target_percent(asset, 0.5)

Вызовы заявок в Ziplime асинхронные и требуют указать стиль исполнения:

from ziplime.finance.execution import MarketOrder, LimitOrder

await context.order(asset, 100, style=MarketOrder())
await context.order_target_percent(asset, 0.5, style=MarketOrder())
await context.order(asset, 100, style=LimitOrder(limit_price=300.0))

Методы целевых заявок не учитывают ещё не исполненные открытые заявки. Если старая стратегия многократно отправляет целевые заявки, добавьте проверку:

if not context.get_open_orders(asset):
    await context.order_target_percent(asset, 0.5, style=MarketOrder())

Поиск символов

Классический Zipline обычно находил символы в базе инструментов с учётом даты симуляции. Ziplime получает инструменты через сервис инструментов:

asset = await context.symbol("SBER")
asset = await context.symbol("SBER", mic="MISX")
asset = await context.symbol("SBER@MISX")

Если один тикер встречается на нескольких биржах, передайте mic или используйте форму SYMBOL@MIC. Именованный набор инструментов загружается так:

context.moex_liquid = await context.symbols_universe("MOEX_LIQUID")

Имя набора должно быть заранее зарегистрировано в сервисе инструментов российского контура.

Расписание

Классический Zipline:

def initialize(context):
    schedule_function(
        rebalance,
        date_rule=date_rules.month_end(),
        time_rule=time_rules.market_close(minutes=30),
    )


def rebalance(context, data):
    order_target_percent(context.asset, 1.0)

Ziplime:

from ziplime.finance.execution import MarketOrder
from ziplime.utils.events import date_rules, time_rules


async def initialize(context):
    context.schedule_function(
        rebalance,
        date_rule=date_rules.month_end(),
        time_rule=time_rules.market_close(minutes=30),
    )


async def rebalance(context, data):
    await context.order_target_percent(
        context.asset,
        1.0,
        style=MarketOrder(),
    )

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

Портфель и позиции

В классическом Zipline часто использовался такой код:

amount = context.portfolio.positions[asset].amount
cash = context.portfolio.cash

Ziplime предоставляет итоговые показатели портфеля напрямую, но в текущей среде позиции хранятся во вложенной структуре по биржам и счетам. Используйте вспомогательные методы:

cash = context.portfolio.cash
portfolio_value = context.portfolio.portfolio_value
amount = await context.portfolio.get_asset_positions_amount(asset)
value = await context.portfolio.get_asset_positions_value(asset)

Для позиции по конкретному биржевому инструменту:

amount = await context.portfolio.get_exchange_asset_positions_amount(
    asset,
    exchange_name="MOEX",
)

Значение exchange_name должно совпадать с конфигурацией запуска.

Запись метрик

Эта часть почти не отличается от Zipline:

context.record(signal=signal, cash=context.portfolio.cash)

Записанные значения становятся столбцами итоговой таблицы результатов.

Перенос пайплайнов

Ziplime включает API Pipeline в стиле Zipline:

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})

Подключите пайплайн в initialize:

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

Получите результат после инициализации:

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

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

Запуск перенесённых алгоритмов

Примеры классического Zipline часто напрямую вызывают run_algorithm(...) с данными pandas или именами пакетов. Стандартный процесс в Ziplime:

Загрузить данные в пакет Ziplime или использовать уже загруженный пакет.
Загрузить пакет через bundle_service.load_bundle(...).
Передать загруженный источник данных в run_simulation(...).
В параметре algorithm_file указать перенесённый .py-файл стратегии.

result = await run_simulation(
    start_date=start_date,
    end_date=end_date,
    trading_calendar="XMOS",
    algorithm_file="my_migrated_algo.py",
    total_cash=10_000_000.0,
    market_data_source=market_data,
    custom_data_sources=[],
    emission_rate=datetime.timedelta(days=1),
    benchmark_asset_symbol="SBER",
    stop_on_error=True,
    asset_service=asset_service,
)

В примере стартовый капитал — 10 000 000 рублей. Идентификатор "XMOS" должен поддерживаться установленным календарём; если российский контур зарегистрировал календарь под другим именем, используйте имя из его конфигурации.

Полный пример до и после

Классический Zipline:

from zipline.api import order_target_percent, record, symbol


def initialize(context):
    context.asset = symbol("SBER")
    context.window = 20


def handle_data(context, data):
    history = data.history(context.asset, "close", context.window, "1d")
    price = data.current(context.asset, "close")
    mean_price = history.mean()

    if price > mean_price:
        order_target_percent(context.asset, 1.0)
    else:
        order_target_percent(context.asset, 0.0)

    record(price=price, mean_price=mean_price)

Ziplime:

from ziplime.finance.execution import MarketOrder


async def initialize(context):
    context.asset = await context.symbol("SBER")
    context.window = 20


async def handle_data(context, data):
    history = await data.history(
        assets=[context.asset],
        fields=["close"],
        bar_count=context.window,
    )
    current = await data.current(
        assets=[context.asset],
        fields=["close"],
    )

    price = current["close"][0]
    mean_price = history["close"].mean()

    target = 1.0 if price > mean_price else 0.0

    if not context.get_open_orders(context.asset):
        await context.order_target_percent(
            context.asset,
            target,
            style=MarketOrder(),
        )

    context.record(price=price, mean_price=mean_price, target=target)

Контрольный список миграции

Замените импорты zipline.api прямыми вызовами context и импортами вспомогательных объектов Ziplime.
Сделайте initialize, handle_data и запланированные функции асинхронными.
Добавьте await при поиске инструментов, доступе к данным, размещении и отмене заявок.
Передавайте списки в data.current и data.history.
Перепишите операции pandas на Polars или явно вызывайте .to_pandas().
Передавайте в методы заявок стиль исполнения, например MarketOrder().
Используйте def before_trading_start, а не async def before_trading_start.
Используйте def analyze, а не async def analyze.
Замените прямой доступ к portfolio.positions[asset] вспомогательными методами портфеля.
Для неоднозначных символов передавайте MIC-код, например MISX.
Перенесите настройку запуска в run_simulation(...) с пакетами данных Ziplime российского контура.

Введение

Разработка стратегий

Справочник языка

Переход на ZipLime

Ограничения

Миграция с классического Zipline

Что осталось знакомым

Краткая таблица преобразований

Импорты

Функции жизненного цикла

`initialize`

`handle_data`

`before_trading_start`

`analyze`

Различия в работе с рыночными данными

Различия в работе с заявками

Поиск символов

Расписание

Портфель и позиции

Запись метрик

Перенос пайплайнов

Запуск перенесённых алгоритмов

Полный пример до и после

Контрольный список миграции

​Что осталось знакомым

​Краткая таблица преобразований

​Импорты

​Функции жизненного цикла

​initialize

​handle_data

​before_trading_start

​analyze

​Различия в работе с рыночными данными

​Различия в работе с заявками

​Поиск символов

​Расписание

​Портфель и позиции

​Запись метрик

​Перенос пайплайнов

​Запуск перенесённых алгоритмов

​Полный пример до и после

​Контрольный список миграции

Что осталось знакомым

Краткая таблица преобразований

Импорты

Функции жизненного цикла

`initialize`

`handle_data`

`before_trading_start`

`analyze`

Различия в работе с рыночными данными

Различия в работе с заявками

Поиск символов

Расписание

Портфель и позиции

Запись метрик

Перенос пайплайнов

Запуск перенесённых алгоритмов

Полный пример до и после

Контрольный список миграции