This R function, `calcExcessModel`, calculates "excess model returns" for a...

This R function, calcExcessModel, calculates "excess model returns" for a given set of financial data (core.mat) by comparing it to a model (model.mat). It refines or adjusts financial performance metrics based on the model's returns for matching strategies and substrategies at specific dates, and returns the adjusted values.

Detailed Steps:

1. Initialize Default Return:

   • The function begins by creating an extended matrix core.temp.mat from core.mat. It adds a new column, ret_excessmod, initialized to the same values as core.mat[,"ret"]. This column will hold adjusted "excess model returns."

2. Identify Keys:

   • The unique combinations of strategy name (name_strategy) and substrategy name (name_substrat) are extracted from core.mat into keys.list. These keys define the groups for which comparisons will be made.

3. Iterate Over Strategy/Substrategy Combinations:

   • For each unique name_strategy and name_substrat pair:
     • The function checks whether the combination exists in model.mat.
     • If it exists:
       • Filter Records by Strategy/Substrategy and Date:
         • Subsets of core.mat (core.sub.mat) and model.mat (model.sub.mat) are created, containing only the rows that match the specific name_strategy, name_substrat, and overlapping dates (dt_record).
       • Aggregate Model Returns:
         • The model.sub.mat data is aggregated by summing the pct_return_netnav values (the model's returns) for each date (dt_record). The result is stored in model.agg.mat.
       • Compare and Adjust Core Returns:
         • For rows in core.mat that match the current combination of name_strategy and name_substrat, the ret_excessmod column is updated. It calls a function, calcExcess, to calculate the difference between live returns (core.sub.mat) and the aggregated model returns (model.agg.mat). The optional pivot.col="name_substrat" suggests the use of substrategies as a pivot for calculations.

4. Return Adjusted Returns:

   • After processing all combinations in keys.list, the function returns the updated column core.temp.mat[,"ret_excessmod"].

What the Code Effectively Does:

• The code adjusts or recalculates the "excess model returns" (ret_excessmod) for live trades in core.mat by comparing them with modeled or expected returns (model.mat).
• The adjustment is calculated for each unique strategy–substrategy combination, using only the date-overlapping records.
• If no matching key (strategy + substrategy) is found in model.mat, the ret_excessmod column remains unchanged for that combination (defaulting to the live return from core.mat).

Practical Use Case:

This function is likely used in financial or investment analysis workflows to evaluate the performance of live-traded strategies against their modeled benchmark returns, at the level of specific strategies and substrategies, on a daily or periodic basis.