Portfolio & Recording

Use context.portfolio to inspect strategy performance and positions during a run. Use context.account for account-level leverage and margin fields. Use context.record(...) to write custom metrics into the final performance output.

Portfolio fields

context.portfolio is a Portfolio object updated as the simulation runs. Common fields:

Field	Meaning
`starting_cash`	Starting cash balance
`cash`	Current cash
`portfolio_value`	Cash plus position value
`pnl`	Profit and loss
`returns`	Current return value
`cash_flow`	Cash changes
`positions_value`	Total market value of positions
`positions_exposure`	Total exposure of positions
`positions`	Positions keyed by `(exchange_name, trading_account_id, listing)`. Prefer the helper methods below

Example:

async def handle_data(context, data):
    cash = context.portfolio.cash
    value = context.portfolio.portfolio_value

    if cash > 10_000:
        ...

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

Position helpers

Prefer helper methods when you need amounts or values for one asset.

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

Return positions that match the underlying asset id. This can aggregate across exchange listings of the same underlying asset.

positions = await context.portfolio.get_asset_positions(context.asset)

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

Return positions that match the exact exchange asset SID.

positions = await context.portfolio.get_exchange_asset_positions(
    context.asset,
    exchange_name="LIME",
)

Amount and value helpers

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="LIME",
)
exchange_value = await context.portfolio.get_exchange_asset_positions_value(
    context.asset,
    exchange_name="LIME",
)

Use the exchange_asset versions when the exact listing matters. Use the asset versions when you want to treat listings of the same underlying asset together.

Position fields

Each Position has:

Field	Meaning
`asset`	Exchange listing
`amount`	Current amount
`cost_basis`	Average cost per share or contract, including commission
`last_sale_price`	Last synced price
`last_sale_date`	Last sale datetime, when available
`exchange_name`, `trading_account_id`	Where the position is held

positions = await context.portfolio.get_asset_positions(context.asset)
for position in positions:
    print(position.amount, position.cost_basis, position.last_sale_price)

Account fields

context.account contains account and leverage metrics. Common fields:

Field	Meaning
`settled_cash`	Settled cash
`buying_power`	Buying power
`equity_with_loan`	Equity with loan value
`total_positions_value`	Total position value
`total_positions_exposure`	Total position exposure
`available_funds`	Available funds
`excess_liquidity`	Excess liquidity
`leverage`	Gross leverage
`net_leverage`	Net leverage
`net_liquidation`	Net liquidation value
`initial_margin_requirement`, `maintenance_margin_requirement`	Margin the book requires, including futures
`accrued_interest`	Bond coupon accrued on the book

Example:

from ziplime.finance.execution import MarketOrder

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

Recording custom metrics

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

Recorded values are added to the daily performance output and are available in analyze.

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

You can also pass alternating positional name/value pairs:

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

Prefer keyword arguments for readability.

Analyze recorded values

def analyze(context, perf):
    print(perf[["portfolio_value", "cash", "signal"]].tail())

perf is a pandas DataFrame with one row per session, produced after the run. Its exact columns depend on the metrics set and on the names you recorded. perf["positions"] holds a snapshot per session, so recorded rows don’t change as the run proceeds. Define analyze with plain def. For futures, size and risk against notional exposure rather than position value — opening a futures position moves no cash. See Futures, Options & Bonds.

Introduction

Writing Strategies

Strategy Language

Migrating to Ziplime

Limitations

Portfolio & Recording

Portfolio fields

Position helpers

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

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

Amount and value helpers

Position fields

Account fields

Recording custom metrics

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

Analyze recorded values

​Portfolio fields

​Position helpers

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

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

​Amount and value helpers

​Position fields

​Account fields

​Recording custom metrics

​context.record(*args, **kwargs)

​Analyze recorded values

Portfolio fields

Position helpers

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

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

Amount and value helpers

Position fields

Account fields

Recording custom metrics

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

Analyze recorded values