This R function `calcExcess` is designed to calculate excess returns...

June 30, 2025 at 07:01 AM


#################### FUNCTION START ####################
# this function will allocate excess returns based on the granularity defined by pivot.col
calcExcess <- function(core.sub.mat, bm.ret, pivot.col="name_strategy")
{
  n.pivot <- nrow(unique(core.sub.mat[,pivot.col,drop=FALSE]));#updated by kyle on 1/20/2012		
  
  ### first compute the excess return for each strategy ######################	
  tot.wt <- aggregate(list(wt=abs(as.numeric(core.sub.mat[,"wts"]))),
                      list(dt_record=strToDt(core.sub.mat[,"dt_record"])),
                      sum); # total weight of benchmarked strategies aggregated by date
  agg.pivot <- aggregate(list(ret=as.numeric(core.sub.mat[,"ret"]),
                              wt=abs(as.numeric(core.sub.mat[,"wts"]))),
                         list(dt_record=strToDt(core.sub.mat[,"dt_record"]),
                              name_pivot=core.sub.mat[,pivot.col]),
                         sum); # get the return and weight PER PIVOT
  wt.agg.pivot <- agg.pivot[,"wt"] / tot.wt[match(agg.pivot[,"dt_record"],tot.wt[,"dt_record"]),"wt"]; # determine the weight of the strategy to the whole benchmarked set - need this if multiple pivots match to one bm
  wt.agg.pivot[is.nan(wt.agg.pivot)] <- 0. # for those with 0 weight (resulting in div by 0)
  ret.excess.pivot <- agg.pivot[,"ret"] - wt.agg.pivot*rep(bm.ret,n.pivot);	# distribute the benchmark excess to each pivot
  
  ### compute the excess return contribution for each SUBPIVOT ##################	
  # this will match each subpivot to its pivot and return the appropriate row indexes (like a vlookup) - i.e. if only one total pivot then all should have same match
  # i.e. this is necessary in the case where multiple tickers are mapped to one strategy (i.e. allocate to multiple tickers in Enhanced strategy)
  pivot.map.idx <- match(paste(core.sub.mat[,"dt_record"],core.sub.mat[,pivot.col],sep="|"),
                         paste(dtToString(agg.pivot[,"dt_record"]),agg.pivot[,"name_pivot"],sep="|"));
  wt.pivot <- abs(as.numeric(core.sub.mat[,"wts"])) / agg.pivot[pivot.map.idx,"wt"]; # determine the weights of each subpivot to its pivot
  wt.pivot[is.nan(wt.pivot)] <- 0.;
  wt.pivot*ret.excess.pivot[pivot.map.idx];
  #core.mat[core.mat[,"benchmark"]==bm.list[i],"ret_excess"] <- wt.strat*ret.excess.strat[strat.map.idx];
}
#################### FUNTION END ####################

This R function calcExcess is designed to calculate excess returns for a set of financial strategies or sub-strategies, based on a benchmark return (bm.ret) and a specified granularity level (pivot.col). Let's break down what the code is doing:

Purpose:

The function calculates excess returns for individual strategies or sub-pivots within a dataset. For finance, "excess returns" typically refer to the returns generated above a benchmark's return, weighted appropriately by allocation or importance.

The granularity of the grouping (determined by pivot.col) allows the user to aggregate and calculate excess returns at a specific strategy or category level.

Input Parameters:

core.sub.mat: A data frame or matrix containing inputs for the calculations. It should include:
- "dt_record": Dates for the time periods.
- "ret": Returns for each row.
- "wts": Weights (allocations) corresponding to each return.
- Other columns, including the pivot column specified by pivot.col.
bm.ret: A scalar representing the benchmark return, possibly a vector or constant return value.
pivot.col: (Default: "name_strategy") A string specifying the column name that determines the group or strategy to aggregate returns on.

How the Code Works:

Set Up Number of Pivot Levels:
- The function determines how many unique values exist in the pivot.col. This indicates the number of strategies or pivot groups for calculating excess returns.
Aggregate Total Weights by Dates:
- The code first sums the absolute values of the weights (wts) per date (dt_record) using aggregate.
- This produces the total weight for all strategies on each day.
Aggregate Returns and Weights for Each Pivot Level:
- Using the grouping column (pivot.col), the function aggregates the returns and weights per group and date.
Compute Weight Proportions for Each Pivot:
- The weight for each pivot strategy relative to the total weight (tot.wt) across all strategies is calculated.
- This ensures the function considers the relative proportion of each pivot's contribution to the benchmark.
Calculate Excess Returns for Each Pivot:
- Excess returns for each pivot strategy (ret.excess.pivot) are calculated as: [ \text{Excess Return} = \text{Pivot Return} - (\text{Weight Proportion} \times \text{Benchmark Return}) ]
Match Sub-Pivots to Their Pivot Group:
- Sub-pivots (rows in the dataset) are matched to their aggregated pivot-level data. This is necessary to allocate excess returns back to sub-pivots.
Compute Weights of Sub-Pivots Within Pivots:
- Within a pivot, weights of sub-pivots are computed (wt.pivot), and they are normalized relative to the pivot total weight.
Allocate Excess Returns to Sub-Pivots:
- Each sub-pivot is allocated a proportion of the pivot's excess return, using the calculated weights of sub-pivots.

Final Output:

The function returns nothing directly (perhaps because the function is incomplete). However, it internally calculates:

ret.excess.pivot: The excess return for each pivot strategy.
Allocated excess returns for sub-pivots (last computation).

Currently, the last computed result (wt.pivot * ret.excess.pivot[pivot.map.idx]) is not stored or returned, which suggests that either the function is incomplete or expects further implementation to handle the results.

Key Notes:

Dependencies:
- The function requires strToDt and dtToString functions for date conversions. These seem to be custom functions, as they are not native to R.
Ensure Input Data Structure:
- The input core.sub.mat needs to contain specific columns like "dt_record", "ret", "wts", and the grouping column pivot.col.
Incomplete Implementation:
- The function appears incomplete as it doesn't return or modify any data explicitly, though it performs the excess return calculation.
Use Case:
- The function would likely be used in financial applications where strategies or portfolios are benchmarked against a common index/return, and there is a need to determine excess performance contributions at granular levels (strategies or sub-strategies).

Generate your own explanations

Download our vscode extension

Read other generated explanations