macrosynergy.panel.basket#

Basket class for calculating the returns and carries of baskets of financial contracts using various weighting methods.

class Basket(df, contracts, ret='XR_NSA', cry=None, start=None, end=None, blacklist=None, ewgts=None)[source]#

Bases: object

Calculates the returns and carries of baskets of financial contracts using various weighting methods.

Parameters:

df (DataFrame) – standardized DataFrame containing the columns: ‘cid’, ‘xcat’, ‘real_date’ and ‘value’.
contracts (List[str]) – base tickers (combinations of cross-sections and base categories) that define the contracts that go into the basket.
ret (str) – return category postfix to be appended to the contract base; default is “XR_NSA”.
cry (Union[str, List[str]]) – carry category postfix; default is None. The field can either be a single carry or multiple carries defined in a List.
start (str) – earliest date in ISO 8601 format. Default is None.
end (str) – latest date in ISO 8601 format. Default is None.
blacklist (dict) – cross-sections with date ranges that should be excluded from the DataFrame. If one cross-section has several blacklist periods append numbers to the cross-section code.
ewgts (List[str]) – one or more postfixes that may identify exogenous weigh :param List[str] ewgts: one or more postfixes that may identify exogenous weight categories. Similar to return postfixes they are appended to base tickers.

N.B.: Each instance of the class will update associated standardised DataFrames, containing return and carry categories, and external weights.

store_attributes(df, pfx, pf_name)[source]#

Adds multiple attributes to class based on postfixes that denote carry or external weight types.

Parameters:

df (DataFrame) – original, standardised DataFrame.
pfx (List[str]) – category postfixes involved in the basket calculation.
pf_name (str) – associated name of the postfix “cry” or “wgt”.

Note: These are [1] flags of existence of carry and weight strings in class, [2] lists of tickers related to all postfixes, [3] a dictionary of wide time series panel dataframes for all postfixes.

static pivot_dataframe(df, tick_list)[source]#

Reduces the standardised DataFrame to include a subset of the possible tickers and, subsequently returns a wide dataframe: each column corresponds to a ticker.

Parameters:

tick_list – list of the respective tickers.
df – standardised dataframe.

Return <pd.DataFrame> dfw:

wide dataframe.

static date_check(date_string)[source]#

Validates that the dates passed are valid timestamp expressions and will convert to the required form ‘%Y-%m-%d’. Will raise an assertion if not in the expected form.

Parameters:: date_string – valid date expression. For instance, “1st January, 2000.”

static check_weights(weight)[source]#

Checks if all rows in dataframe add up to roughly 1.

Parameters:: weight (DataFrame) – weight dataframe.

static max_weight_func(weights, max_weight)[source]#

Enforces maximum weight caps or - if impossible applies equal weight.

Parameters:

weights (DataFrame) – Corresponding weight matrix. Multidimensional.
max_weight (float) – Upper-bound on the weight allowed for each cross-section.

Return <pd.DataFrame>:

Will return the modified weight DataFrame.

N.B.: If the maximum weight is less than the equal weight weight, this replaces the computed weight with the equal weight. For instance, [np.nan, 0.63, np.nan, np.nan, 0.27] becomes [np.nan, 0.5, np.nan, np.nan, 0.5]. Otherwise, the function calls the ConvergeRow Class to ensure all weights “converge” to a value within the upper-bound. Allow for a margin of error set to 0.001.

equal_weight(df_ret)[source]#

Calculates dataframe of equal weights based on available return data.

Parameters:: df_ret (DataFrame) – wide time-indexed data frame of returns.
Return <pd.DataFrame>:: dataframe of weights.

Note: The method determines the number of non-NA cross-sections per timestamp, and subsequently distributes the weights evenly across non-NA cross-sections.

Return type:: DataFrame

fixed_weight(df_ret, weights)[source]#

Calculates fixed weights based on a single list of values and a corresponding return panel dataframe.

Parameters:

df_ret (DataFrame) – Return series matrix. Multidimensional.
weights (List[float]) – List of floats determining weight allocation.

Return <pd.DataFrame>:

panel of weights

inverse_weight(dfw_ret, lback_meth='xma', lback_periods=21, remove_zeros=True)[source]#

Calculates weights inversely proportionate to recent return standard deviations.

Parameters:

dfw_ret (DataFrame) – panel dataframe of returns.
lback_meth (str) – Lookback method for “invsd” weighting method. Default is “xma”.
lback_periods (int) – Lookback periods. Default is 21. Half-time for “xma” and full lookback period for “ma”.
remove_zeros (bool) – Any returns that are exact zeros will not be included in the lookback window and prior non-zero values are added to the window instead.

Return <pd.DataFrame>:

Dataframe of weights.

N.B.: The rolling standard deviation will be calculated either using the standard moving average (ma) or the exponential moving average (xma). Both will require returns before a first weight can be computed.

values_weight(dfw_ret, dfw_wgt, weight_meth)[source]#

Returns weights based on an external weighting category.

Parameters:

dfw_ret (DataFrame) – Standard wide dataframe of returns across time and contracts.
dfw_wgt (DataFrame) – Standard wide dataframe of weight category values across time and contracts.
weight_meth (str) –

Return <pd.DataFrame>:

Dataframe of weights.

make_weights(weight_meth='equal', weights=None, lback_meth='xma', lback_periods=21, ewgt=None, max_weight=1.0, remove_zeros=True)[source]#

Returns wide dataframe of weights to be used for basket series.

Parameters:

weight_meth (str) – method used for weighting constituent returns and carry. The parameter can receive either a single weight method or multiple weighting methods. See make_basket docstring.
weights (List[float]) – single list of weights corresponding to the base tickers in contracts argument. This is only relevant for the fixed weight method.
lback_meth (str) – look-back method for “invsd” weighting method. Default is Exponential MA, “ema”. The alternative is simple moving average, “ma”.
lback_periods (int) – look-back periods for “invsd” weighting method. Default is 21. Half-time for “xma” and full lookback period for “ma”.
ewgt (str) – Exogenous weight postfix that defines the weight value panel. Only needed for the ‘values’ or ‘inv_values’ method.
max_weight (float) – maximum weight of a single contract. Default is 1, i.e zero restrictions. The purpose of the restriction is to limit concentration within the basket.
remove_zeros (bool) – removes the zeros. Default is set to True.

return: <pd.DataFrame>: wide dataframe of contract weights across time.

static column_manager(df_cat, dfw_wgs)[source]#

Will match the column names of the two dataframes involved in the computation: either the return & weight dataframes or the carry & weight dataframes. The pandas multiply operation requires the column names, of both dataframes involved in the binary operation, to be identical.

Parameters:

df_cat (DataFrame) – return or carry dataframe.
dfw_wgs (DataFrame) – weight dataframe.

Return <pd.DataFrame> dfw_wgs:

modified weight dataframe (column names will map to the other dataframe received).

column_weights(dfw_wgs)[source]#

The weight dataframe is used to compute the basket performance for returns, carries etc. Therefore, with their broad application, the column names of the dataframe should correspond to the ticker postfix of each contract.

Parameters:: dfw_wgs (DataFrame) – weight dataframe.
Return <pd.DataFrame> dfw_wgs:: weight dataframe with updated columns names.

make_basket(weight_meth='equal', weights=None, lback_meth='xma', lback_periods=21, ewgt=None, max_weight=1.0, remove_zeros=True, basket_name='GLB_ALL')[source]#

Calculates all basket performance categories.

Parameters:

weight_meth (str) –
method used for weighting constituent returns and carry. The parameter can receive either a single weight method or multiple weighting methods. The options are as follows: [1] “equal”: all constituents with non-NA returns have the same weight.

This is the default.

[2] “fixed”: weights are proportionate to a single list of values provided
which are passed to argument weights (each value corresponds to a single contract).

[3] “invsd”: weights based on inverse to standard deviations of recent
returns.

[4] “values”: weights proportionate to a panel of values of exogenous weight
category.

[5] “inv_values”: weights are inversely proportionate to of values of
exogenous weight category.
weights (List[float]) – single list of weights corresponding to the base tickers in contracts argument. This is only relevant for the fixed weight method.
lback_meth (str) – look-back method for “invsd” weighting method. Default is Exponential MA, “ema”. The alternative is simple moving average, “ma”.
lback_periods (int) – look-back periods for “invsd” weighting method. Default is 21. Half-time for “xma” and full lookback period for “ma”.
ewgt (str) – Exogenous weight postfix that defines the weight value panel. Only needed for the ‘values’ or ‘inv_values’ method.
max_weight (float) – maximum weight of a single contract. Default is 1, i.e zero restrictions. The purpose of the restriction is to limit concentration within the basket.
remove_zeros (bool) – removes the zeros. Default is set to True.
basket_name (str) – name of basket base ticker (analogous to contract name) to be used for return and (possibly) carry are calculated. Default is “GLB_ALL”.

weight_visualiser(basket_name, start_date=None, end_date=None, subplots=True, facet_grid=False, scatter=False, all_tickers=True, single_ticker=None, percentage_change=False, size=(7, 7))[source]#

Method used to visualise the weights associated with each contract in the basket.

Parameters:

basket_name – name of basket whose weights are visualized
start_date (str) – start date of he visualisation period.
end_date (str) – end date of the visualization period.
subplots (bool) – contract weights are displayed on different plots (True) or on a single plot (False).
facet_grid (bool) – parameter used to break up the plot into multiple cartesian coordinate systems. If the basket consists of a high number of contracts, using the Facet Grid is recommended.
scatter (bool) – if the facet_grid parameter is set to True there are two options: i) scatter plot if there a lot of blacklist periods; ii) line plot for continuous series.
all_tickers (bool) – if True (default) all weights are displayed. If set to False single-ticker must be specified.
single_ticker (str) – individual ticker for further, more detailed, analysis.
percentage_change (bool) – graphical display used to further assimilate the fluctuations in the contract’s weight. The graphical display is limited to a single contract. Therefore, pass the ticker into the parameter “single_ticker”.
size (Tuple[int, int]) – size of the plot. Default is (7, 7).

static column_split(df)[source]#

Receives a dataframe with the columns ‘ticker’, ‘real_date’ and ‘value’ and returns a standardised dataframe with the columns ‘cid’, ‘xcat’, ‘real_date’ and ‘value. The ‘ticker’ column is broken up to produce the two new columns.

Parameters:: df (DataFrame) –
Return <pd.DataFrame> df:: standardised dataframe.

return_basket(basket_names=None)[source]#

Return standardized dataframe of basket performance data based on one or more weighting methods.

Parameters:: basket_names (Union[str, List[str]]) – single basket name or list for which performance data are to be returned. If none is given all baskets added to the instance are selected.
Return <pd.Dataframe>:: standardized DataFrame with the basket return and (possibly) carry data in standard form, i.e. columns ‘cid’, ‘xcat’, ‘real_date’ and ‘value’.

return_weights(basket_names=None)[source]#

Return the standardised dataframe containing the corresponding weights used to compute the basket.

Parameters:: basket_names (Union[str, List[str]]) – single basket name or list for which performance data are to be returned. If none is given all baskets added to the instance are selected.
Return <pd.Dataframe>:: standardized DataFrame with basket weights.