sim_platform.research.pnl_attribution

PnL attribution of one run: alpha, beta, factor exposure and trading costs.

Returns are the run’s per-bar equity returns (evaluation.run_period_returns). The market factor is buying and holding the traded symbols in equal weights over the same bars; further factors (for example Fama-French daily returns) can be supplied as series aligned with those periods. The regression is ordinary least squares,

r_run = alpha + sum_k beta_k * f_k + e,

with classical standard errors. Alpha is per period and annualised by the bar length. Costs split the money paid on fills into commission, borrow and market impact (the difference between the impacted fill price and the quoted price, when an impact model was used). Spread paid is not separated: fills record the price paid, not the mid.

sim_platform.research.pnl_attribution.regress(returns, factors)[source]

OLS of returns on an intercept and each factor; coefficients with t-statistics.

Returns {'alpha', 'alpha_t', 'betas': {name: {'beta', 't'}}, 'r_squared', 'residual_volatility', 'periods'}, or {'periods', 'reason'} when there are too few periods or the factors are collinear.

Parameters:
  • returns (Sequence[float])

  • factors (Mapping[str, Sequence[float]])

Return type:

Dict[str, Any]

sim_platform.research.pnl_attribution.market_returns(view, stamps)[source]

Equal-weight buy-and-hold returns of the run’s symbols between stamps.

A symbol’s price at a stamp is its latest bar close ending by then, or its first open before its first bar ends, the convention of metrics.portfolio_series. None when a symbol has no bars.

Parameters:
  • view (Mapping[str, Any])

  • stamps (Sequence[int])

Return type:

List[float] | None

sim_platform.research.pnl_attribution.periods_per_year(stamps)[source]

Bars per trading year, from the median bar length in market time.

Parameters:

stamps (Sequence[int])

Return type:

float | None

sim_platform.research.pnl_attribution.open_short_borrow(report, view)[source]

Borrow accrued on shorts still open when the run ended, in money units.

The ledger charges borrow when a short is covered; a short open at the end has accrued borrow that no fill paid. This replays the run’s fills with the same rule (execution.costs) and accrues each open short from its share-weighted opening time to the run’s last event, at the run’s borrow_bps_per_year.

Parameters:
  • report (Dict[str, Any])

  • view (Mapping[str, Any])

Return type:

int

sim_platform.research.pnl_attribution.trading_costs(report, view)[source]

Commission, borrow and market impact paid on fills, in money units and bps.

borrow includes borrow_accrued: borrow on shorts still open at the end.

Parameters:
  • report (Dict[str, Any])

  • view (Mapping[str, Any])

Return type:

Dict[str, Any]

sim_platform.research.pnl_attribution.pnl_attribution(report, factors=None)[source]

Alpha, beta to the traded market, other factor exposures and costs of one run.

Parameters:
  • report (Dict[str, Any]) – A saved run report (Platform.report_data).

  • factors (Mapping[str, Sequence[float]] | None) – Optional extra factor return series, one value per run period (the periods between consecutive points of the run’s equity curve).

Returns:

market and factors are regression results (see regress) with alpha_annual added; costs comes from trading_costs; pnl holds net PnL and gross PnL before costs, in money units.

Return type:

{'periods', 'periods_per_year', 'market', 'factors', 'costs', 'pnl'}