macrosynergy.signal.target_positions#

Functionality to create contract-specific target positions from signals.

weight_dataframes(df, basket_names=None)[source]#

Helper function used to break up the original dataframe and create the wide weight dataframes.

Parameters:
Return <List[pd.DataFrames], dict>:

modify_signals(df, cids, xcat_sig, start=None, end=None, scale='prop', min_obs=252, thresh=None)[source]#

Calculate modified cross-section signals based on zn-scoring (proportionate method) or conversion to signs (digital method).

Parameters:

  • df (DataFrame) – standardized DataFrame containing the following columns: ‘cid’, ‘xcat’, ‘real_date’ and ‘value’.

  • cids (List[str]) – cross sections of markets or currency areas in which positions should be taken.

  • xcat_sig (str) – category that serves as signal across markets.

  • start (str) – earliest date in ISO format. Default is None and earliest date for which the signal category is available is used.

  • end (str) – latest date in ISO format. Default is None and latest date for which the signal category is available is used.

  • scale (str) –

    method to translate signals into target positions: [1] Default is ‘prop’, means proportionate. In this case zn-scoring is applied

    to the signal based on the panel, with the neutral level set at zero. A 1 SD value translates into a USD1 position in the contract.

    [2] Method ‘dig’ means ‘digital’ and sets the individual position to either USD1

    long or short, depending on the sign of the signal. Note that a signal of zero translates into a position of zero.

  • min_obs (int) – the minimum number of observations required to calculate zn_scores. Default is 252. Note: For the initial period of the signal time series in-sample zn-scoring is used.

  • thresh (float) – threshold value beyond which zn-scores for propotionate position taking are winsorized. The threshold is the maximum absolute score value in standard deviations. The minimum is 1 standard deviation.

Return <pd.Dataframe>:

standardized dataframe, of modified signaks, using the columns ‘cid’, ‘xcat’, ‘real_date’ and ‘value’.

cs_unit_returns(df, contract_returns, sigrels, ret='XR_NSA')[source]#

Calculate returns of composite unit positions (that jointly depend on one signal).

Parameters:

  • df (DataFrame) – standardized DataFrame containing the following columns: ‘cid’, ‘xcat’, ‘real_date’ and ‘value’.

  • contract_returns (List[str]) – list of the contract return types.

  • sigrels (List[str]) – respective signal for each contract type.

  • ret (str) – postfix denoting the returns in % applied to the contract types.

Return <pd.Dataframe>:

standardized dataframe with the summed portfolio returns which are used to calculate the evolving volatility, using the columns ‘cid’, ‘xcat’, ‘real_date’ and ‘value’.

basket_handler(df_mods_w, df_c_wgts, contracts)[source]#

Function designed to compute the target positions for the constituents of a basket. The function will return the corresponding basket dataframe of positions.

Parameters:

  • df_mods_w (DataFrame) – target position dataframe. Will be multiplied by the weight dataframe to establish the positions for the basket of constituents.

  • df_c_wgts (DataFrame) – weight dataframe used to adjust the positions of the basket of contracts.

  • contracts (List[str]) – the constituents that make up each basket.

Return <pd.Dataframe>:

basket positions weight-adjusted.

date_alignment(panel_df, basket_df)[source]#

Method used to align the panel position dataframe and the basket dataframe of weight-adjusted positions to the same timeframe.

Parameters:
Return <Tuple[pd.DataFrame, pd.DataFrame]>:

returns the two received dataframes defined over the same period.

consolidation_help(panel_df, basket_df)[source]#

The function receives a panel dataframe and a basket of cross-sections of the same contract type. Therefore, aim to consolidate the targeted positions across the shared contracts.

Parameters:
Return <Tuple[pd.DataFrame, pd.DataFrame]>:

returns the consolidated and reduced dataframes.

consolidate_positions(data_frames, ctypes)[source]#

Method used to consolidate positions if baskets are used. The constituents of a basket will be a subset of one of the panels.

Parameters:
Return <List[pd.DataFrame]>:

list of dataframes having consolidated positions.

target_positions(df, cids, xcat_sig, ctypes, sigrels, basket_names=[], ret='XR_NSA', start=None, end=None, scale='prop', min_obs=252, thresh=None, cs_vtarg=None, lback_periods=21, lback_meth='ma', half_life=11, posname='POS')[source]#

Converts signals into contract-specific target positions.

Parameters:

  • df (DataFrame) – standardized DataFrame containing at least the following columns: ‘cid’, ‘xcat’, ‘real_date’ and ‘value’.

  • cids (List[str]) – cross-sections of markets or currency areas in which positions should be taken.

  • xcat_sig (str) – category that serves as signal across markets.

  • ctypes (Union[List[str], str]) – contract types that are traded across markets. They should correspond to return categories in the dataframe if the ret argument is appended. Examples are ‘FX’ or ‘EQ’.

  • basket_names (Union[str, List[str]]) – single string or list of the names of several baskets. The weight dataframes will be appended to the main dataframe. Therefore, use the basket name to isolate the corresponding weights. The default value for the parameter is an empty list, which mean that no baskets are traded.

  • sigrels (List[float]) – values that translate the single signal into contract type and basket signals in the order defined by keys.

  • ret (str) – postfix denoting the returns in % associated with contract types. For JPMaQS derivatives return data this is typically “XR_NSA” (default). Returns are required for volatility targeting.

  • start (str) – earliest date in ISO format. Default is None and earliest date for which the signal category is available is used.

  • end (str) – latest date in ISO format. Default is None and latest date for which the signal category is available is used.

  • scale (str) –

    method that translates signals into unit target positions: [1] Default is ‘prop’ for proportionate. In this case zn-scoring is applied

    to the signal based on the panel, with the neutral level set at zero. A 1 SD value translates into a USD1 position in the contract. This translation may apply winsorization through the thresh argument

    [2] Method ‘dig’ means ‘digital’ and sets the individual position to either USD1

    long or short, depending on the sign of the signal. Note that a signal of zero translates into a position of zero.

    Note that unit target positions may subsequently be calibrated to meet cross- section volatility targets using the cs_targ argument.

  • min_obs (int) – the minimum number of observations required to calculate zn_scores. Default is 252. Note: For the initial minimum period of the signal time series in-sample zn-scoring is used.

  • thresh (float) – threshold value beyond which zn-scores for proportionate position taking are winsorized. The threshold is the maximum absolute score value in standard deviations. The minimum is 1 standard deviation.

  • cs_vtarg (float) – Value for volatility targeting at the cross-section level. The purpose of this operation is to relate signal to risk rather than notional. Default is None and means no volatility targeting. If a value is chosen then for each cross-section a unit position is defined as a position for which the annual return standard deviation is equal to that value. For example, a target of 10 and a cross-section signal of 0.5 standard deviations would translate into a target position that carries a recent historical annualized standard deviation of 5 dollars (or other currency units).

  • lback_periods – Number of lookback periods over which volatility is calculated. Default is 21. Typically this refers to days.

  • lback_meth (str) – Lookback method to calculate the volatility. Default is “ma”, which means simple moving average. Alternative is “ema”, which means exponential moving average.

  • half_life (int) – Refers to the half-time for “xma”. Default is 11.

  • posname (str) – postfix added to contract to denote position name.

Return <pd.Dataframe>:

standardized dataframe with daily target positions in USD, using the columns ‘cid’, ‘xcat’, ‘real_date’ and ‘value’.

Note: A target position differs from a signal insofar as it is a dollar amount and

determines to what extent the size of signal (as opposed to direction) matters. Further, if the modified signal has a NaN value, the target position will be converted to zero: a position will not be taken given the signal was not available for that respective date. A target position also differs from an actual position in two ways. First, the actual position can only be aligned with the target with some lag. Second, the actual position will be affected by other considerations, such as risk management and assets under management.