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 sweep candidates. Retained 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_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, ts_utc, equity, and period_return. 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_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.

  • 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 <- ledgr_param_grid(flat = list(qty = 0), long = list(qty = 1))
sweep <- ledgr_sweep(exp, grid, retain = ledgr_sweep_retention("completed"))

long <- ledgr_sweep_returns(sweep)
long[!is.na(long$period_return), ]
#> # A tibble: 8 × 5
#>   sweep_id               candidate_id ts_utc              equity period_return
#>   <chr>                  <chr>        <dttm>               <dbl>         <dbl>
#> 1 sweep_d88c58ddc6f51c07 flat         2020-01-02 00:00:00 100000    0         
#> 2 sweep_d88c58ddc6f51c07 flat         2020-01-03 00:00:00 100000    0         
#> 3 sweep_d88c58ddc6f51c07 flat         2020-01-04 00:00:00 100000    0         
#> 4 sweep_d88c58ddc6f51c07 flat         2020-01-05 00:00:00 100000    0         
#> 5 sweep_d88c58ddc6f51c07 long         2020-01-02 00:00:00 100000    0         
#> 6 sweep_d88c58ddc6f51c07 long         2020-01-03 00:00:00 100001    0.0000100 
#> 7 sweep_d88c58ddc6f51c07 long         2020-01-04 00:00:00 100000   -0.00001000
#> 8 sweep_d88c58ddc6f51c07 long         2020-01-05 00:00:00 100002    0.0000200 
ledgr_sweep_returns_wide(sweep, value = "equity")
#> # A tibble: 5 × 3
#>   ts_utc                flat   long
#>   <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_snapshot_close(snapshot)