napistu_torch.evaluation.pathways

Pathway evaluation utilities.

This module provides functions for evaluating how well learned embeddings capture biological pathway structure through similarity analysis.

Public Functions

calculate_pathway_similarities(embedding_matrix, pathway_assignments, pathway_names, filtering_mask=None, priority_pathways=None, device=None)

Calculate pathway similarity based on average within-category cosine similarity.

get_comprehensive_source_membership(sbml_dfs, napistu_graph, pathway_names=None, vertex_summaries=None)

Get comprehensive pathway membership information for vertices.

Functions

calculate_pathway_similarities(...[, ...])

Calculate pathway similarity based on average within-category cosine similarity.

get_comprehensive_source_membership(...)

Get the comprehensive source membership for a given NapistuGraph and SBML_dfs.
napistu_torch.evaluation.pathways._rollup_pathway_similarities(per_category_sim: ndarray, pathway_names: list[str], priority_pathways: list[str] = ['BiGG', 'Dogma', 'IDEA', 'IntAct', 'OmniPath', 'Reactome', 'Reactome-FI', 'STRING', 'TRRUST', 'Recon3D', 'iMM1415', 'iMM904']) → dict[str, float]

Rollup per-category similarities into individual priority pathways and aggregated others.

Parameters:

  • per_category_sim (numpy.ndarray) – (C,) array of average cosine similarities per category

  • pathway_names (list) – category/pathway names corresponding to per_category_sim

  • priority_pathways (list) – priority pathway names (these pathways will be preserved as their own entries)

Returns:

  • Each priority pathway gets its own entry

  • All other pathways are averaged into a single ‘other’ entry

Return type:

dict mapping pathway names to their similarities

napistu_torch.evaluation.pathways._within_category_similarity(embeddings: torch.Tensor, categories: torch.Tensor, device: torch.device = None) → tuple[ndarray, float]

Calculate average within-category cosine similarity (excluding self-pairs).

Parameters:

  • embeddings (torch.Tensor) – (I, K) tensor of feature embeddings

  • categories (torch.Tensor) – (I, C) binary tensor of category memberships

  • device (torch.device) – device to use (if None, uses embeddings.device)

Returns:

per_category_sim: (C,) numpy array of average cosine similarities per category overall_sim: float

average across all categories

Return type:

tuple[np.ndarray, float]

napistu_torch.evaluation.pathways.calculate_pathway_similarities(embedding_matrix: torch.Tensor, pathway_assignments: torch.Tensor, pathway_names: list[str], filtering_mask: torch.Tensor | None = None, priority_pathways: list[str] = ['BiGG', 'Dogma', 'IDEA', 'IntAct', 'OmniPath', 'Reactome', 'Reactome-FI', 'STRING', 'TRRUST', 'Recon3D', 'iMM1415', 'iMM904'], device: torch.device = None) → dict[str, float]

Calculate pathway similarity based on average within-category cosine similarity.

Parameters:

  • embedding_matrix (torch.Tensor) – (I, K) tensor of feature embeddings

  • pathway_assignments (torch.Tensor) – (I, C) binary tensor of category memberships

  • pathway_names (list[str]) – list of category/pathway names corresponding to per_category_sim

  • filtering_mask – optional (I,) tensor of boolean mask to filter embeddings and assignments

Return type:

dict mapping pathway names to their similarities

napistu_torch.evaluation.pathways.get_comprehensive_source_membership(napistu_graph: NapistuGraph, sbml_dfs: SBML_dfs) → VertexTensor

Get the comprehensive source membership for a given NapistuGraph and SBML_dfs.

Parameters:

  • napistu_graph (NapistuGraph) – NapistuGraph object to add the comprehensive source membership from.

  • sbml_dfs (SBML_dfs) – SBML_dfs object containing vertex source information to add to the NapistuGraph.

Returns:

VertexTensor object containing the comprehensive source membership.

Return type:

VertexTensor