macrosynergy.pnl.proxy_pnl_calc#

Module for calculating an approximate nominal PnL under consideration of transaction costs.

proxy_pnl_calc(df, spos, rstring, transaction_costs_object, roll_freqs=None, start=None, end=None, blacklist=None, portfolio_name='GLB', pnl_name='PNL', tc_name='TCOST', bidoffer_name='BIDOFFER', rollcost_name='ROLLCOST', return_pnl_excl_costs=False, return_costs=False, concat_dfs=False)[source]#

Calculates an approximate nominal PnL under consideration of transaction costs

Parameters:

  • df (QuantamentalDataFrame) – standardized JPMaQS DataFrame with the necessary columns: ‘cid’, ‘xcat’, ‘real_date’ and ‘value’. This dataframe must contain the notional positions and related notional return series (for PnL calculations).

  • spos (str) – the name of the strategy positions in the dataframe in the format “<sname>_<pname>”. This must correspond to contract positions in the dataframe, which are categories of the format “<cid>_<ctype>_<sname>_<pname>”. The strategy name <sname> has usually been set by the contract_signals function and the string for <pname> by the notional_positions function.

  • rstring (str) – the string that identifies the returns series in the dataframe.

  • transaction_costs_object (TransactionCosts or dict) – an initialized TransactionCosts object (macrosynergy.pnl.transaction_costs.TransactionCosts) that contains the transaction costs data. If the user does not have access to the TransactionCosts object, or does not want to use transaction costs, the function can be called with transaction_costs_object=None. Users can alternatively pass a dictionary of static cost parameters, which will be adapted to the TransactionCosts interface.

  • roll_freqs (dict) – dictionary of roll frequencies for each contract type. This must use the contract types as keys and frequency string (“w”, “m”, or “q”) as values. The default frequency for all contracts not in the dictionary is “m” for monthly. Default is None: all contracts are rolled monthly.

  • start (str) – the start date of the data. Default is None, which means that the start date is taken from the dataframe.

  • end (str) – the end date of the data. Default is None, which means that the end date is taken from the dataframe.

  • blacklist (dict) – a dictionary of contract identifiers to exclude from the calculation. Default is None, which means that no contracts are excluded.

  • portfolio_name (str) – the name of the portfolio. Default is “GLB”.

  • pnl_name (str) – the name of the PnL (including costs), Default is “PNL”. The series for PnL excluding costs is named with “…<pnl_name>e”. The name is appended with the strategy positions name, as “<portfolio_name>_<spos>_<pnl_name>”.

  • tc_name (str) – the name of the trading costs series. Default is “TCOST”.

  • bidoffer_name (str) – a sub-component of the trading costs, representing the bid-offer spread. Default is “BIDOFFER”.

  • rollcost_name (str) – a sub-component of the trading costs, representing the roll costs. Default is “ROLLCOST”.

  • return_pnl_excl_costs (bool) – whether to return the PnL excluding costs. Default is False.

  • return_costs (bool) – whether to return the trading costs. Default is False.

  • concat_dfs (bool) – whether to concatenate the output dataframes. Default is False.

Notes

Transaction costs as % of notional are considered to be a linear function of size, with the slope determined by the normal and large positions, if all relevant series are applied.

Returns:

When either of return_pnl_excl_costs or return_costs is True, the function returns a tuple of the PnL excluding costs, the PnL including costs, and the trading costs. Otherwise, it returns the PnL including costs. If concat_dfs is True, the function concatenates any output dataframes and returns a single dataframe.

Return type:

Union[QuantamentalDataFrame, Tuple[QuantamentalDataFrame, …]

plot_pnl(df, portfolio_name='GLB', pnl_name='PNL', tc_name='TCOST', cumsum=True, title='Cumulative PnLs and Costs', ylabel='PnL / USD Million', xlabel='Real Date', hline=0.0, **kwargs)[source]#

Plot the PnLs and costs for the portfolio.

Parameters:

  • df (pd.DataFrame) – the dataframe containing the PnLs and costs.

  • portfolio_name (str) – the name of the portfolio. Default is “GLB”.

  • pnl_name (str) – the name of the PnL (including costs). Default is “PNL”.

  • tc_name (str) – the name of the trading costs series. Default is “TCOST”.

  • cumsum (bool) – whether to plot the cumulative sum of the PnLs and costs. Default is True.

  • title (str) – the title of the plot. Default is “Cumulative PnLs and Costs”.

  • ylabel (str) – the label for the y-axis. Default is “PnL / USD Million”.

  • xlabel (str) – the label for the x-axis. Default is “Real Date”.

  • hline (Union[Number, List[Number]]) – the value(s) for the horizontal line(s). Default is 0.0.

  • kwargs (dict) – additional keyword arguments for the plot.

Returns:

The function plots the PnLs and costs for the portfolio.

Return type:

None