> ## 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.

# Портфель и запись метрик

> Проверка состояния портфеля и счёта, а также запись пользовательских метрик

Используйте `context.portfolio`, чтобы во время запуска проверять результаты стратегии и позиции. В `context.account` доступны показатели кредитного плеча, маржи и счёта в целом. Метод `context.record(...)` записывает пользовательские метрики в итоговую таблицу результатов.

## Поля портфеля

`context.portfolio` — объект `Portfolio`, который обновляется по ходу симуляции.

Основные поля:

| Поле                 | Значение                                                                    |
| -------------------- | --------------------------------------------------------------------------- |
| `starting_cash`      | Начальный остаток денежных средств                                          |
| `cash`               | Текущие денежные средства                                                   |
| `portfolio_value`    | Денежные средства плюс стоимость позиций                                    |
| `pnl`                | Прибыль и убыток                                                            |
| `returns`            | Текущая доходность                                                          |
| `cash_flow`          | Изменение денежных средств                                                  |
| `positions_value`    | Общая рыночная стоимость позиций в валюте портфеля                          |
| `positions_exposure` | Общая экспозиция позиций в валюте портфеля                                  |
| `positions`          | В текущей среде — вложенное хранилище позиций по бирже, счёту и инструменту |

Пример для портфеля в рублях:

```python theme={null}
async def handle_data(context, data):
    cash = context.portfolio.cash
    value = context.portfolio.portfolio_value

    if cash > 1_000_000:
        ...

    context.record(cash=cash, portfolio_value=value)
```

## Вспомогательные методы позиций

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

### `await context.portfolio.get_asset_positions(asset, exchange_name=None, trading_account_id=None)`

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

```python theme={null}
positions = await context.portfolio.get_asset_positions(context.asset)
```

### `await context.portfolio.get_exchange_asset_positions(asset, exchange_name=None, trading_account_id=None)`

Возвращает позиции, которые точно соответствуют SID биржевого инструмента.

```python theme={null}
positions = await context.portfolio.get_exchange_asset_positions(
    context.asset,
    exchange_name="MOEX",
)
```

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

### Методы количества и стоимости

```python theme={null}
amount = await context.portfolio.get_asset_positions_amount(context.asset)
value = await context.portfolio.get_asset_positions_value(context.asset)

exchange_amount = await context.portfolio.get_exchange_asset_positions_amount(
    context.asset,
    exchange_name="MOEX",
)
exchange_value = await context.portfolio.get_exchange_asset_positions_value(
    context.asset,
    exchange_name="MOEX",
)
```

Используйте варианты `exchange_asset`, когда важен конкретный листинг. Варианты `asset` подходят, если разные листинги одного базового инструмента нужно рассматривать вместе.

## Поля позиции

Каждый объект `Position` содержит:

| Поле              | Значение                                     |
| ----------------- | -------------------------------------------- |
| `asset`           | Биржевой инструмент                          |
| `amount`          | Текущее количество                           |
| `cost_basis`      | Средняя стоимость одной акции или контракта  |
| `last_sale_price` | Последняя синхронизированная цена            |
| `last_sale_date`  | Дата и время последней сделки, если доступны |

```python theme={null}
positions = await context.portfolio.get_asset_positions(context.asset)
for position in positions:
    print(position.amount, position.cost_basis, position.last_sale_price)
```

## Поля счёта

`context.account` содержит показатели счёта и кредитного плеча.

Основные поля:

| Поле                       | Значение                                            |
| -------------------------- | --------------------------------------------------- |
| `settled_cash`             | Денежные средства после расчётов                    |
| `buying_power`             | Покупательная способность                           |
| `equity_with_loan`         | Собственные средства с учётом стоимости обеспечения |
| `total_positions_value`    | Общая стоимость позиций в валюте портфеля           |
| `total_positions_exposure` | Общая экспозиция позиций в валюте портфеля          |
| `available_funds`          | Доступные средства                                  |
| `excess_liquidity`         | Избыточная ликвидность                              |
| `leverage`                 | Валовая величина кредитного плеча                   |
| `net_leverage`             | Чистая величина кредитного плеча                    |
| `net_liquidation`          | Чистая ликвидационная стоимость                     |

Пример:

```python theme={null}
from ziplime.finance.execution import MarketOrder

if context.account.leverage > 1.5:
    await context.order_target_percent(context.asset, 0.0, style=MarketOrder())
```

## Запись пользовательских метрик

### `context.record(*args, **kwargs)`

Записанные значения добавляются в ежедневную таблицу результатов и доступны в `analyze`.

```python theme={null}
context.record(
    signal=signal,
    short_ma=short_ma,
    long_ma=long_ma,
    cash=context.portfolio.cash,
)
```

Также можно передать чередующиеся позиционные пары «имя — значение»:

```python theme={null}
context.record("signal", signal, "cash", context.portfolio.cash)
```

Для удобства чтения предпочтительнее именованные аргументы.

## Анализ записанных значений

```python theme={null}
def analyze(context, perf):
    print(perf[["portfolio_value", "cash", "signal"]].tail())
```

`perf` формируется после завершения запуска. Точный набор столбцов зависит от набора метрик и имён, переданных в `context.record`.