`contango.trading.analysis.graphing.parameter_importance`

contango.trading.analysis.graphing.parameter_importance

ParameterImportance

ParameterImportance(config: C)

Bases: GraphType[ParameterImportanceConfig]

A graph type that shows the sensitivity of a metric to each swept parameter.

Source code in src\contango\trading\analysis\graph_type.py

def __init__(self, config: C) -> None:
    """
    Initializes `GraphType`.

    Args:
        config: The matching configuration for the graph type.
    """
    self._config = config

build

build(df: DataFrame) -> go.Figure

Builds the parameter importance bar chart.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	The tidy experiment DataFrame.	required

Returns:

Type	Description
`Figure`	A plotly Figure.

Source code in src\contango\trading\analysis\graphing\parameter_importance.py

def build(self, df: pd.DataFrame) -> go.Figure:
    """
    Builds the parameter importance bar chart.

    Args:
        df: The tidy experiment DataFrame.

    Returns:
        A plotly Figure.
    """
    importance_df = compute_parameter_importance(df, self.config.target_metric, self.config.param_columns)

    fig = px.bar(   # type: ignore[unknownMemberType]
        importance_df,
        x="importance",
        y="parameter",
        orientation="h",
        title=f"Parameter Importance: sensitivity of {self.config.target_metric} to each parameter",
        labels={"importance": "Relative Importance (eta²)", "parameter": "Parameter"},
    )
    fig.update_layout(yaxis={"categoryorder": "total ascending"})  # type: ignore[unknownMemberType]
    return fig

ParameterImportanceConfig `dataclass`

ParameterImportanceConfig(param_columns: list[str], target_metric: str = 'calmar_ratio')

Bases: GraphConfig

A graph configuration specific to the parameter importance graph.

Attributes:

Name	Type	Description
`param_columns`	`list[str]`	The parameter columns to score.
`target_metric`	`str`	The name for the targeted metric to explain.

compute_parameter_importance

compute_parameter_importance(df: DataFrame, target_metric: str, param_columns: list[str]) -> pd.DataFrame

Scores each parameter's importance to target_metric using an eta-squared measure.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Experiment DataFrame.	required
`target_metric`	`str`	The metric column to explain (e.g. "calmar_ratio").	required
`param_columns`	`list[str]`	Parameter columns to score.	required

Returns:

Type	Description
`DataFrame`	DataFrame with columns ["parameter", "importance"], sorted descending.

Source code in src\contango\trading\analysis\graphing\parameter_importance.py

def compute_parameter_importance(
    df: pd.DataFrame,
    target_metric: str,
    param_columns: list[str],
) -> pd.DataFrame:
    """
    Scores each parameter's importance to target_metric using an
    eta-squared measure.

    Args:
        df: Experiment DataFrame.
        target_metric: The metric column to explain (e.g. "calmar_ratio").
        param_columns: Parameter columns to score.

    Returns:
        DataFrame with columns ["parameter", "importance"], sorted descending.
    """
    plot_df = df.dropna(subset=[target_metric])
    grand_mean = plot_df[target_metric].mean()
    ss_total = ((plot_df[target_metric] - grand_mean) ** 2).sum()

    scores: list[dict[str, str | float]] = []
    for param in param_columns:
        group_stats = plot_df.groupby(param)[target_metric].agg(["mean", "count"])
        ss_between = (group_stats["count"] * (group_stats["mean"] - grand_mean) ** 2).sum()
        importance = float(ss_between / ss_total) if ss_total > 0 else 0.0
        scores.append({"parameter": param, "importance": importance})

    return pd.DataFrame(scores).sort_values("importance", ascending=False).reset_index(drop=True)

contango.trading.analysis.graphing.parameter_importance