napistu_torch.evaluation.edge_weights

Edge weight sensitivity analysis utilities.

This module provides functions for analyzing how edge features influence learned edge weights through gradient-based sensitivity analysis.

Public Functions

compute_edge_feature_sensitivity(edge_encoder, edge_attr, max_edges, device=None)

Compute mean edge-weight gradients with respect to edge features.

format_edge_feature_sensitivity(sensitivity, feature_names, top_k=10)

Format sensitivity results as a DataFrame with feature names and rankings.

plot_edge_feature_sensitivity(sensitivity, feature_names, top_k=10, figsize=(10, 6))

Create a horizontal bar plot showing top-k most sensitive edge features.

Functions

compute_edge_feature_sensitivity(...[, device])

Compute mean edge-weight gradients with respect to edge features.

format_edge_feature_sensitivity(...)

Format edge feature sensitivities into a DataFrame.

plot_edge_feature_sensitivity(...[, top_n, ...])

Create a signed waterfall plot for feature sensitivities.
napistu_torch.evaluation.edge_weights._resolve_device(edge_encoder: torch.nn.Module, device: str | torch.device | None) → torch.device
napistu_torch.evaluation.edge_weights.compute_edge_feature_sensitivity(edge_encoder: torch.nn.Module, edge_attr: torch.Tensor, max_edges: int, device: str | torch.device | None = None) → torch.Tensor

Compute mean edge-weight gradients with respect to edge features.

Parameters:

  • edge_encoder (nn.Module) – Trained edge encoder that maps attributes to scalar weights.

  • edge_attr (Tensor) – Edge attribute matrix of shape [num_edges, edge_dim].

  • max_edges (int) – Number of edges to sample uniformly at random for the gradient estimate.

  • device (Optional[Union[str, torch.device]], optional) – Device used for the computation. Defaults to the encoder’s parameter device when None.

Returns:

One-dimensional tensor containing the mean gradient per feature with shape [edge_dim].

Return type:

Tensor

Raises:

ValueError – If edge_attr is empty or max_edges is not positive.

napistu_torch.evaluation.edge_weights.format_edge_feature_sensitivity(edge_feature_sensitivities: torch.Tensor, napistu_data) → DataFrame

Format edge feature sensitivities into a DataFrame.

Parameters:

  • edge_feature_sensitivities (Tensor) – One-dimensional tensor containing the mean gradient per feature with shape [edge_dim].

  • napistu_data (NapistuData) – NapistuData object containing edge feature names.

Returns:

DataFrame with columns: feature_name, sensitivity, absolute_sensitivity.

Return type:

pd.DataFrame

napistu_torch.evaluation.edge_weights.plot_edge_feature_sensitivity(formatted_feature_sensitivities, top_n=20, figsize=(16, 8), truncate_names=50)

Create a signed waterfall plot for feature sensitivities.

Parameters:

formatted_feature_sensitivitiespd.DataFrame

DataFrame with columns: feature_name, sensitivity, absolute_sensitivity

top_nint

Number of top features to display (by absolute sensitivity)

figsizetuple

Figure size (width, height)

truncate_namesint or None

Maximum length for feature names. None = no truncation