macrosynergy.visuals.score_visualisers

class ScoreVisualisers(df, xcats=None, cids=None, cid_labels=None, xcat_labels=None, xcat_comp='Composite', weights=None, blacklist=None, sequential=True, iis=True, neutral='mean', pan_weight=1, thresh=3, min_obs=261, est_freq='m', postfix='_ZN', normalize_weights=True, signs=None, complete_xcats=False, no_zn_scores=False, rescore_composite=False)

Bases: object

Class to visualize the z-scores and linear composite of specified categories and cross-sections.

Parameters:

• df (DataFrame) – A standardized JPMaQS with the following columns: ‘cid’, ‘xcat’, ‘real_date’, and at least one metric from - ‘value’, ‘grading’, ‘eop_lag’, or ‘mop_lag’.

• cids (List[str], optional) – A list of cross-section identifiers to select from the DataFrame. If None, all cross-sections in the frame are selected. Default is None.

• xcats (List[str], optional) – A list of category tickers to select from the DataFrame. If None, all categories are selected. Default is None.

• xcat_labels (Dict[str, str], optional) – A dictionary mapping category tickers (keys) to their labels (values). Default is None.

• cid_labels (Dict[str, str], optional) – A dictionary mapping cross-section identifiers (keys) to their labels (values). Default is None.

• xcat_comp (str) – The name of the composite category. Default is ‘Composite’.

• weights (List[float]) – A list of weights for the linear composite. Default is equal weights. The length of the list must be equal to the number of categories in xcats. If weights do not add up to 1, they are normalized.

• normalize_weights (bool) – If True (default), normalize weights if they do not add to one.

• signs (List[float]) – A list of signs in order to use both negative and positive values of categories for the linear composite. This must have the same length as weights and xcats, and correspondes to the order of categories in xcats. Default is all positive.

• blacklist (Dict[str, str]) – A dictionary of cross-sections (keys) and date ranges (values) that should be excluded. If one cross-section has several blacklist periods append numbers to the cross-section identifier.

• complete_xcats (bool) – If True, all xcats must have data for the composite to be calculated. Default is False, which means that the composite is calculate if at least one category has data.

• no_zn_scores (bool) – Per default, all categories are scored before they are averaged into the composite. If True, the class does not calculate scores and takes the average of the original categiries. This is useful if those are already score or of similar scale.

• rescore_composite (bool) – If True, the composite is re-scored to a normal unit scale. Default is False.

• sequential (bool) – if True (default) score parameters (neutral level and mean absolute deviation) are estimated sequentially with concurrently available information only.

• min_obs (int) – the minimum number of observations required to calculate zn_scores. Default is 261. The parameter is only applicable if the “sequential” parameter is set to True. Otherwise the neutral level and the mean absolute deviation are both computed in- sample and will use the full sample.

• iis (bool) – if True (default) zn-scores are also calculated for the initial sample period defined by min-obs on an in-sample basis to avoid losing history. This is irrelevant if sequential is set to False.

• neutral (str) – The method to calculate the neutral score. Default is ‘zero’. Alternatives are ‘mean’, ‘median’ or a number.

• pan_weight (float) – The weight of panel (versus individual cross section) for calculating the z-score parameters, i.e. the neutral level and the mean absolute deviation. Default is 1, i.e. panel data are the basis for the parameters. Lowest possible value is 0, i.e. parameters are all specific to cross section.

• thresh (float) – The threshold value beyond which scores are winsorized, i.e. contained at that threshold. The threshold is the maximum absolute score value that the function is allowed to produce. The minimum threshold is 1 mean absolute deviation.

• est_freq (str) – the frequency at which mean absolute deviations or means are re-estimated. The options are daily, weekly, monthly & quarterly: “D”, “W”, “M”, “Q”. Default is monthly. Re-estimation is performed at period end.

• postfix (str) – The string appended to category name for output; default is “_ZN”.

view_snapshot(cids=None, xcats=None, transpose=False, date=None, annot=True, title=None, title_fontsize=20, figsize=(20, 10), xcat_labels=None, xticks=None, yticks_rotation=None, round_decimals=2, cmap=None, cmap_range=None, sort_by_composite=False, composite_to_end=False, return_as_df=False)

View heatmap of the scores at the specified or latest available date.

Parameters:

• cids (List[str]) – A list of cross-section identifiers to select from the DataFrame. If None, all cross-sections in the frame are selected.

• xcats (List[str]) – A list of category tickers to select from the DataFrame. If None, all categories are selected.

• transpose (bool) – If True, transpose the snapshot so cross-section identifiers are on the x-axis and category tickers are on the y-axis.

• date (str) – ISO-8601 formatted date. The date of the snapshot. If None, the latest date in the DataFrame is selected. Unless the date is today, then the latest date is set to the previous business day.

• annot (bool) – If True, annotate the heatmap.

• title (str) – The title of the heatmap.

• title_fontsize (int) – The fontsize of the title.

• figsize (tuple) – The size of the figure.

• xcat_labels (dict) – A dictionary mapping category tickers to their labels.

• xticks (dict) – A dictionary of arguments to label the x axis.

• yticks_rotation (int) – The rotation of the y-axis labels.

• round_decimals (int) – The number of decimals to round the scores to.

• cmap (str) – The colormap of the heatmap.

• cmap_range (tuple) – The range of the colormap.

• return_as_df (bool) – If True, return the DataFrame instead of plotting it.

view_score_evolution(xcat, freq='A', cids=None, include_latest_period=True, include_latest_day=True, start=None, transpose=False, annot=True, title=None, title_fontsize=20, xticks=None, figsize=(20, 10), cid_labels=None, cmap=None, cmap_range=None, round_decimals=2, return_as_df=False)

View the evolution of the scores for the specified category and cross-sections.

Parameters:

• xcat (str) – The category to view the evolution of.

• freq (str) – The frequency of the evolution. Must be ‘Q’, ‘A’, or ‘BA’.

• cids (List[str]) – A list of cross-section identifiers to select from the DataFrame. If None, all in the dataframe are selected.

• include_latest_period (bool) – If True, include the latest period in the evolution.

• include_latest_day (bool) – If True, include the latest day in the evolution. If the latest date is today, then the latest date is set to the previous business day.

• date (str) – ISO-8601 formatted date. The date of the snapshot. If None, the latest date in the DataFrame is selected.

• start (str) – ISO-8601 formatted date. Select data from this date onwards. If None, all dates are selected.

• transpose (bool) – If True, transpose the evolution so cross-section identifiers are on the x-axis and dates are on the y-axis.

• annot (bool) – If True, annotate the heatmap.

• title (str) – The title of the heatmap.

• title_fontsize (int) – The fontsize of the title.

• xticks (dict) – A dictionary of arguments to label the x axis.

• figsize (tuple) – The size of the figure.

• cid_labels (dict) – A dictionary mapping cross-section identifiers to their labels.

• round_decimals (int) – The number of decimals to round the scores to.

• cmap (str) – The colormap of the heatmap.

• cmap_range (tuple) – The range of the colormap.

• return_as_df (bool) – If True, return the DataFrame instead of plotting it.

view_cid_evolution(cid, xcats, freq, include_latest_period=True, include_latest_day=True, start=None, transpose=False, annot=True, title=None, title_fontsize=20, figsize=(20, 10), xticks=None, xcat_labels=None, cmap=None, cmap_range=None, round_decimals=2, composite_to_end=False, return_as_df=False)

View the evolution of the scores for the specified cross-section and categories.

Parameters:

• cid (str) – The cross-section to view the evolution of.

• xcats (List[str]) – A list of category tickers to select from the DataFrame. If None, all are selected.

• freq (str) – The frequency of the evolution. Must be ‘Q’, ‘A’, or ‘BA’.

• include_latest_period (bool) – If True, include the latest period in the evolution.

• include_latest_day (bool) – If True, include the latest day in the evolution. If the latest date is today, then the latest date is set to the previous business day.

• start (str) – ISO-8601 formatted date. Select data from this date onwards. If None, all dates are selected.

• transpose (bool) – If True, transpose the evolution so xcats are on the x-axis and dates are on the y-axis.

• annot (bool) – If True, annotate the heatmap.

• title (str) – The title of the heatmap.

• title_fontsize (int) – The fontsize of the title.

• xticks (dict) – A dictionary of arguments to label the x axis.

• figsize (tuple) – The size of the figure.

• xcat_labels (dict) – A dictionary mapping xcats to their labels.

• round_decimals (int) – The number of decimals to round the scores to.

• cmap (str) – The colormap of the heatmap.

• cmap_range (tuple) – The range of the colormap.

• return_as_df (bool) – If True, return the DataFrame instead of plotting it.