Skip to contents

Retained sweep return series

Source: R/sweep-retention.R
ledgr_sweep_returns.Rd

ledgr_sweep_returns() returns the retained long net portfolio equity and adjacent-period return series for completed and explicitly labelled incomplete sweep candidates. Complete-performance panel projections exclude incomplete candidates. returns are net strategy returns only; they are not benchmark-relative returns and they do not include gross-vs-net attribution.

Usage

ledgr_sweep_returns(x, candidates = NULL)

ledgr_sweep_trades(x, candidates = NULL)

ledgr_sweep_returns_wide(x, candidates = NULL, value = c("returns", "equity"))

ledgr_sweep_returns_panel(
  x,
  candidates = NULL,
  value = c("returns", "equity"),
  complete = TRUE
)

ledgr_sweep_returns_matrix(
  x,
  candidates = NULL,
  value = c("returns", "equity"),
  complete = TRUE
)

ledgr_sweep_returns_data_frame(
  x,
  candidates = NULL,
  value = c("returns", "equity"),
  complete = TRUE
)

ledgr_sweep_returns_xts(
  x,
  candidates = NULL,
  value = c("returns", "equity"),
  complete = TRUE
)

Arguments

x

A ledgr_sweep_results object.

candidates

Optional character vector of candidate_id values.

value

Value to widen. "returns" uses period_return; "equity" uses equity.

complete

Logical scalar. If TRUE, require every selected completed candidate to share the same timestamp grid after first-row handling.

Value

ledgr_sweep_returns() returns a tibble with sweep_id, candidate_id, status, ts_utc, equity, and period_return. ledgr_sweep_trades() returns retained closed-trade evidence with sweep_id, candidate_id, candidate_row, trade_seq, close_ts_utc, realized_pnl, and win_loss. ledgr_sweep_returns_wide() returns a tibble with ts_utc followed by one column per candidate. ledgr_sweep_returns_panel() returns a classed list with normalized long evidence, a numeric matrix, UTC timestamps, the candidate ids used, completed candidate ids, excluded candidate ids, and first-row handling metadata. ledgr_sweep_returns_matrix(), ledgr_sweep_returns_data_frame(), and ledgr_sweep_returns_xts() return adapter-shaped projections over that normalized panel.

Functions

  • ledgr_sweep_trades(): Return retained closed-trade evidence for completed sweep candidates. This evidence is captured at sweep time from closed trade rows and is not reconstructed from saved fills.

  • ledgr_sweep_returns_wide(): Return retained sweep return or equity series in wide form. Use the long form when you want candidate metadata beside each row; use the wide form when an external metric package expects one return/equity column per candidate. Candidate IDs that collide with the structural ts_utc column or the reserved ..ledgr_candidate_ prefix are represented by that prefix followed by their lowercase UTF-8 hex bytes.

  • ledgr_sweep_returns_panel(): Return a normalized retained-return panel. For value = "returns", the structural first timestamp is dropped after verifying each candidate's first period_return is NA_real_.

  • ledgr_sweep_returns_matrix(): Return a numeric T x N matrix over a normalized retained-return panel.

  • ledgr_sweep_returns_data_frame(): Return a base data frame over a normalized retained-return panel.

  • ledgr_sweep_returns_xts(): Return an optional xts projection over a normalized retained-return panel. The xts package remains optional and is not imported by ledgr.

Examples

bars <- data.frame(
  instrument_id = "AAA",
  ts_utc = as.POSIXct("2020-01-01", tz = "UTC") + 86400 * 0:4,
  open = c(10, 11, 12, 11, 13),
  high = c(11, 12, 13, 12, 14),
  low = c(9, 10, 11, 10, 12),
  close = c(10, 11, 12, 11, 13),
  volume = 1000
)
snapshot <- ledgr_snapshot_from_df(bars, db_path = tempfile(fileext = ".duckdb"))
strategy <- function(ctx, params) {
  targets <- ctx$flat()
  targets["AAA"] <- params$qty
  targets
}
exp <- ledgr_experiment(snapshot, strategy, cost_model = ledgr_cost_zero())
grid <- data.frame(qty = c(0, 1))
sweep <- ledgr_sweep(
  exp,
  grid,
  retain = ledgr_sweep_retention(returns = "completed", trades = "closed")
)

long <- ledgr_sweep_returns(sweep)
long[!is.na(long$period_return), ]
#> # A tibble: 8 × 6
#>   sweep_id          candidate_id status ts_utc              equity period_return
#>   <chr>             <chr>        <chr>  <dttm>               <dbl>         <dbl>
#> 1 sweep_333eae2d69… strategy_3a… DONE   2020-01-02 00:00:00 100000    0         
#> 2 sweep_333eae2d69… strategy_3a… DONE   2020-01-03 00:00:00 100000    0         
#> 3 sweep_333eae2d69… strategy_3a… DONE   2020-01-04 00:00:00 100000    0         
#> 4 sweep_333eae2d69… strategy_3a… DONE   2020-01-05 00:00:00 100000    0         
#> 5 sweep_333eae2d69… strategy_ee… DONE   2020-01-02 00:00:00 100000    0         
#> 6 sweep_333eae2d69… strategy_ee… DONE   2020-01-03 00:00:00 100001    0.0000100 
#> 7 sweep_333eae2d69… strategy_ee… DONE   2020-01-04 00:00:00 100000   -0.00001000
#> 8 sweep_333eae2d69… strategy_ee… DONE   2020-01-05 00:00:00 100002    0.0000200 
ledgr_sweep_returns_wide(sweep, value = "equity")
#> # A tibble: 5 × 3
#>   ts_utc              strategy_3a1f1a127b38 strategy_eeb75fd8d6af
#>   <dttm>                              <dbl>                 <dbl>
#> 1 2020-01-01 00:00:00                100000                100000
#> 2 2020-01-02 00:00:00                100000                100000
#> 3 2020-01-03 00:00:00                100000                100001
#> 4 2020-01-04 00:00:00                100000                100000
#> 5 2020-01-05 00:00:00                100000                100002
ledgr_sweep_trades(sweep)
#> # A tibble: 0 × 7
#> # ℹ 7 variables: sweep_id <chr>, candidate_id <chr>, candidate_row <int>,
#> #   trade_seq <int>, close_ts_utc <dttm>, realized_pnl <dbl>, win_loss <chr>

returns <- ledgr_sweep_returns_matrix(sweep)
dim(returns)
#> [1] 4 2
head(ledgr_sweep_returns_data_frame(sweep))
#>                      strategy_3a1f1a127b38 strategy_eeb75fd8d6af
#> 2020-01-02T00:00:00Z                     0            0.0000e+00
#> 2020-01-03T00:00:00Z                     0            1.0000e-05
#> 2020-01-04T00:00:00Z                     0           -9.9999e-06
#> 2020-01-05T00:00:00Z                     0            2.0000e-05
if (requireNamespace("xts", quietly = TRUE)) {
  head(ledgr_sweep_returns_xts(sweep))
}
#>            strategy_3a1f1a127b38 strategy_eeb75fd8d6af
#> 2020-01-02                     0            0.0000e+00
#> 2020-01-03                     0            1.0000e-05
#> 2020-01-04                     0           -9.9999e-06
#> 2020-01-05                     0            2.0000e-05

ledgr_snapshot_close(snapshot)