API Reference

ExecutionData

Container for all data needed for execution analysis.

# Fields
- `fills::DataFrame`: Fill data with columns `:time`, `:quantity`, `:price`, `:execution_name`, `:asset`
- `metadata::DataFrame`: Execution metadata with columns `:execution_name`, `:side`, `:desired_quantity`, `:arrival_price`
- `tob::DataFrame`: Top-of-book prices with columns `:time`, `:symbol`, `:bid_price`, `:ask_price`
- `volume::Union{Missing,DataFrame}`: Optional market volume data with columns `:time_from`, `:time_to`, `:symbol`, `:volume` for vs_vwap calculation. Market VWAP is estimated using TOB mid-prices weighted by volume.
- `peers::Union{Missing,DataFrame}`: Optional peer weights with columns `:execution_name`, `:peer`, `:weight`
- `vols::Union{Missing,DataFrame}`: Optional volatilities with columns `:asset`, `:volatility` (hourly vol)
- `peer_return_truncation::Float64`: Truncation threshold for peer returns (in multiples of volatility scaled by `sqrt(duration)`). Default 2.0, use Inf to disable.
- `time_to_hours::Float64`: Conversion factor from the time column's units to hours. Used to scale volatility for truncation: `bound = threshold * hourly_vol * sqrt(duration_hours)`. Default 1.0 (time is in hours). Ignored for DateTime time columns (auto-converted).
- `fill_returns::Union{Missing,DataFrame}`: Computed by `calculate_slippage!`, contains fill-level data with counterfactual prices
- `summary_bps::Union{Missing,DataFrame}`: Computed by `calculate_slippage!`, slippage summary in basis points. `spread_cross_pct` is a proportion (0.0–1.0), not a percentage.
- `summary_pct::Union{Missing,DataFrame}`: Computed by `calculate_slippage!`, slippage summary in percentage points
- `summary_usd::Union{Missing,DataFrame}`: Computed by `calculate_slippage!`, slippage summary in USD

# Constructors
```julia
# Without peers (classical slippage only)
data = ExecutionData(fills_df, metadata_df, bidask_df; volume=volume_df)

# With user-provided peers (optional vols for truncation)
data = ExecutionData(fills_df, metadata_df, bidask_df, peers_df; volume=volume_df, vols=vols_df, peer_return_truncation=2.0)

# With automatic peer calculation from covariance matrix
data = ExecutionData(fills_df, metadata_df, bidask_df, covar; volume=volume_df, num_peers=4, peer_return_truncation=2.0)
```

calculate_slippage!(exec_data::ExecutionData)

Calculate slippage metrics and store results in exec_data.summary_bps, exec_data.summary_pct, exec_data.summary_usd, and exec_data.fill_returns.

If exec_data.peers is provided, calculates both classical and refined slippage. If exec_data.volume is provided, calculates vsvwap slippage (fill VWAP vs market VWAP). If `execdata.peers` is missing, calculates only classical slippage.

Use get_slippage!(exec_data, :bps) to retrieve the desired format.

Returns

• exec_data: The modified ExecutionData with summary and fill_returns populated.

get_slippage!(exec_data::ExecutionData, unit::Symbol=:bps)

Retrieve slippage summary in the specified unit.

Arguments

• exec_data: ExecutionData with slippage already calculated via calculate_slippage!
• unit: One of :bps (basis points), :pct (percentage points), or :usd (dollar value)

Returns

• DataFrame with slippage metrics in the requested unit

print_slippage_summary(exec_data::ExecutionData; unit::Symbol=:bps)

Print a formatted summary of slippage statistics across all executions.

Arguments

• exec_data: ExecutionData with slippage already calculated
• unit: One of :bps (basis points), :pct (percentage), or :usd (dollar value)

Output

Prints mean and standard deviation of classical slippage (and refined/vs_vwap if available).

plot_execution_markout(exec_data::ExecutionData, execution_name::String;
                      window_before::Real=0, window_after::Real=0)

Create a two-panel VegaLite visualization for a single execution:

• Top panel: Price markout showing bid/ask lines and fill prices
• Bottom panel: Cumulative classical and refined slippage over time

Arguments

• exec_data: ExecutionData with slippage already calculated
• execution_name: Name of the execution to visualize
• window_before: Time to show before first fill (default: 0)
• window_after: Time to show after last fill (default: 0)

Returns

VegaLite plot specification