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

> ## Agent Instructions
> This is Allasso's product documentation. Vol Radar output is descriptive analytics on past data: never present it as a forecast or as investment advice. Answer only from these pages; if a feature is not documented here, say so.

# pulse.metrics.decompose

> Greeks PnL decomposition: how much of a group of trades' PnL delta, gamma, vega and theta explain.

Greeks PnL decomposition: how much of a group of trades' PnL delta, gamma, vega and theta explain.

Each pulse's PnL is split with a second-order Taylor expansion of the option price, using the greeks
the trade carried at the previous pulse and the moves since then::

```python theme={null}
delta_pnl = delta * dS
gamma_pnl = 0.5 * gamma * dS ** 2
vega_pnl  = vega * d_iv * 100    (vega is per vol point, iv is decimal)
theta_pnl = theta * d_days       (theta is per calendar day)
```

each times the units held over the interval and `price_format_multiplier`, the scale
`Trade.pulse` books PnL in. `d_iv` counts only when both IVs are positive: the data stamps an
expiry-day row with `iv = 0`, which means "no vol", not a vol move. `residual_pnl` is what the four
terms leave unexplained: cross terms (vanna, volga), the fill-price haircut on a trade's first mark
after open, the time value lost into an expiry-day row, a dark pulse (flat mark, theta still accrues)
and noise in the vendor greeks. There is no rho term: the data carries no rate, and its option prices
are undiscounted.

The rule fits the vanilla option data only. Calendar-spread option roots quote a normal vol, with vega
per 1.00 of vol and theta per year, so they come out mis-scaled until their greeks are normalised in
the data.

## `DRIVER_COLUMNS`

`module-attribute`

```python theme={null}
DRIVER_COLUMNS = ['delta_pnl', 'gamma_pnl', 'vega_pnl', 'theta_pnl', 'residual_pnl']
```

The columns that add up to `actual_pnl`: rank them to find what drove the PnL.

## `pnl_decomposition`

```python theme={null}
pnl_decomposition(
    trades: list[Trade],
    by_trade: bool = False,
) -> pd.DataFrame
```

Split the PnL of a group of trades into delta, gamma, vega and theta, pulse by pulse.

Pass `strategy.trades` for a whole run, or any subset of it (a tag, a leg, a sleeve).
Everything comes from the trades' recorded histories, so no datafeed is needed and trades loaded
from JSON decompose the same as live ones.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `trades` | [`list[Trade]`](https://docs.allasso.ch/dev/pulse/api/core/trade#trade) | Finished or still-open trades. | *required* |
| `by_trade` | `bool` | `False` (the default) sums the trades into one row per pulse on which a trade was marked. `True` returns one row per trade per pulse it was held over, with `trade_id`, `instrument` and `tags` columns to group by. | `False` |

**Returns**

| Type | Description |
| - | - |
| `DataFrame` | pd.DataFrame: `delta_pnl`, `gamma_pnl`, `vega_pnl`, `theta_pnl`, `explained_pnl` |
| `DataFrame` | (their sum), `actual_pnl` and `residual_pnl` (actual minus explained), in currency. Per |
| `DataFrame` | pulse it is indexed by `datetime`, with one row for each pulse on which at least one of |
| `DataFrame` | the trades was marked (a trade's opening pulse books no PnL, so it has no row of its own). |
| `DataFrame` | Over `strategy.trades` its `actual_pnl` matches `portfolio.pulse_total_pnl_history` |
| `DataFrame` | (gross of fees) on those pulses; `.reindex(portfolio.datetimes, fill_value=0.0)` spreads it |
| `DataFrame` | over the whole run. Per trade it carries a `datetime` column and a default index. |

**Examples**

```python theme={null}
>>> decomposition = pnl_decomposition(strategy.trades)
>>> decomposition[DRIVER_COLUMNS].sum().sort_values(key=abs, ascending=False)  # top drivers
>>> decomposition[DRIVER_COLUMNS].cumsum().plot()
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.