Skip to content

trading.analyzer.graphing.pairwise_heatmap_grid

trading.analyzer.graphing.pairwise_heatmap_grid

build_pairwise_heatmap_grid 

build_pairwise_heatmap_grid(df: DataFrame, param_x: str, param_y: str, facet_param: str, target_metric: str = 'calmar_ratio', max_cols: int = 4) -> go.Figure

Builds a grid of 2D heatmaps: param_x vs. param_y, one panel per unique value of facet_param.

Parameters:

Name Type Description Default
df DataFrame

Experiment DataFrame.

 required
param_x str

Parameter column for the heatmap x-axis.

 required
param_y str

Parameter column for the heatmap y-axis.

 required
facet_param str

Parameter column to facet panels by.

 required
target_metric str

Metric column used for cell color. Defaults to "calmar_ratio" (risk-adjusted, better for spotting robust regions than raw return).

 'calmar_ratio'
max_cols int

Maximum number of panels per row before wrapping.

 4

Returns:

Type Description
Figure

A plotly Figure with one subplot per facet_param value.
Source code in src\contango\trading\analyzer\graphing\pairwise_heatmap_grid.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def build_pairwise_heatmap_grid(
    df: pd.DataFrame,
    param_x: str,
    param_y: str,
    facet_param: str,
    target_metric: str = "calmar_ratio",
    max_cols: int = 4,
) -> go.Figure:
    """
    Builds a grid of 2D heatmaps: param_x vs. param_y, one panel per unique
    value of facet_param.

    Args:
        df: Experiment DataFrame.
        param_x: Parameter column for the heatmap x-axis.
        param_y: Parameter column for the heatmap y-axis.
        facet_param: Parameter column to facet panels by.
        target_metric: Metric column used for cell color. Defaults to
                       "calmar_ratio" (risk-adjusted, better for spotting robust regions
                       than raw return).
        max_cols: Maximum number of panels per row before wrapping.

    Returns:
        A plotly Figure with one subplot per facet_param value.
    """
    plot_df = df.dropna(subset=[param_x, param_y, facet_param, target_metric])
    facet_values = sorted(plot_df[facet_param].unique())

    n = len(facet_values)
    cols = min(n, max_cols)

    if cols == 0:
        raise ValueError("No trades were made! Could not graph the pairwise heatmap grid.")

    rows = math.ceil(n / cols)

    fig = make_subplots(
        rows=rows,
        cols=cols,
        subplot_titles=[f"{facet_param}={v}" for v in facet_values],
        shared_xaxes=True,
        shared_yaxes=True,
    )

    zmin, zmax = plot_df[target_metric].min(), plot_df[target_metric].max()

    for i, val in enumerate(facet_values):
        mask: pd.Series = plot_df[facet_param] == val
        subset: pd.DataFrame = plot_df[mask]
        pivot = subset.pivot_table(index=param_y, columns=param_x, values=target_metric, aggfunc="mean")

        fig.add_trace(  # type: ignore[unknownMemberType]
            go.Heatmap(
                z=pivot.values,
                x=pivot.columns,
                y=pivot.index,
                coloraxis="coloraxis",
            ),
            row=(i // cols) + 1,
            col=(i % cols) + 1,
        )

    fig.update_layout(  # type: ignore[unknownMemberType]
        title=f"Pairwise Heatmap Grid — {param_x} × {param_y}, faceted by {facet_param} (color = {target_metric})",
        coloraxis={"colorscale": "RdYlGn", "cmin": zmin, "cmax": zmax},
        height=320 * rows,
    )
    return fig