pyg-nightly 2.7.0.dev20250211__py3-none-any.whl → 2.7.0.dev20250213__py3-none-any.whl

{pyg_nightly-2.7.0.dev20250211.dist-info → pyg_nightly-2.7.0.dev20250213.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyg-nightly
-Version: 2.7.0.dev20250211
+Version: 2.7.0.dev20250213
 Summary: Graph Neural Network Library for PyTorch
 Keywords: deep-learning,pytorch,geometric-deep-learning,graph-neural-networks,graph-convolutional-networks
 Author-email: Matthias Fey <matthias@pyg.org>

{pyg_nightly-2.7.0.dev20250211.dist-info → pyg_nightly-2.7.0.dev20250213.dist-info}/RECORD

@@ -1,4 +1,4 @@
-torch_geometric/__init__.py,sha256=w6FK2cWfDKMk6__QpIY3W_iaTmbYGeA71r1ni5R1cZk,1904
+torch_geometric/__init__.py,sha256=wOLNLy1SUhTvDg4h0bCQM5edX6RXk83qnn4omNGqmaw,1904
 torch_geometric/_compile.py,sha256=f-WQeH4VLi5Hn9lrgztFUCSrN_FImjhQa6BxFzcYC38,1338
 torch_geometric/_onnx.py,sha256=V9ffrIKSqhDw6xUZ12lkuSfNs48cQp2EeJ6Z19GfnVw,349
 torch_geometric/backend.py,sha256=lVaf7aLoVaB3M-UcByUJ1G4T4FOK6LXAg0CF4W3E8jo,1575
@@ -288,8 +288,8 @@ torch_geometric/loader/shadow.py,sha256=_hCspYf9SlJYX0lqEjxFec9e9t1iMScNThOoWR1w
 torch_geometric/loader/temporal_dataloader.py,sha256=AQ2QFeiXKbPp6I8sUeE8H7br-1_yndivXt7Z6_w62zI,2248
 torch_geometric/loader/utils.py,sha256=f27mczQ7fEP2HpTsJGJxKS0slPu0j8zTba3jP8ViNck,14901
 torch_geometric/loader/zip_loader.py,sha256=3lt10fD15Rxm1WhWzypswGzCEwUz4h8OLCD1nE15yNg,3843
-torch_geometric/metrics/__init__.py,sha256=9gPEg0_oMfq7LAr5rsrebasnvYN9nDXwq2ML56lWcMo,529
-torch_geometric/metrics/link_pred.py,sha256=H-s9U9n2CKpj9pRQWG9KdTZ0jueds1iy7hr893BmGoE,23121
+torch_geometric/metrics/__init__.py,sha256=3krvDobW6vV5yHTjq2S2pmOXxNfysNG26muq7z48e94,699
+torch_geometric/metrics/link_pred.py,sha256=X8LXJvJ0dwjOeO0PvB6xe-qkBntmefHKC4zex7Q2i0I,29766
 torch_geometric/nn/__init__.py,sha256=RrWRzEoqtR3lsO2lAzYXboLPb3uYEX2z3tLxiBIVWjc,847
 torch_geometric/nn/data_parallel.py,sha256=lDAxRi83UNuzAQSj3eu9K2sQheOIU6wqR5elS6oDs90,4764
 torch_geometric/nn/encoding.py,sha256=QNjwWczYExZ1wRGBmpuqYbn6tB7NC4BU-DEgzjhcZqw,3115
@@ -630,6 +630,6 @@ torch_geometric/utils/undirected.py,sha256=H_nfpI0_WluOG6VfjPyldvcjL4w5USAKWu2x5
 torch_geometric/visualization/__init__.py,sha256=PyR_4K5SafsJrBr6qWrkjKr6GBL1b7FtZybyXCDEVwY,154
 torch_geometric/visualization/graph.py,sha256=ZuLPL92yGRi7lxlqsUPwL_EVVXF7P2kMcveTtW79vpA,4784
 torch_geometric/visualization/influence.py,sha256=CWMvuNA_Nf1sfbJmQgn58yS4OFpeKXeZPe7kEuvkUBw,477
-pyg_nightly-2.7.0.dev20250211.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
-pyg_nightly-2.7.0.dev20250211.dist-info/METADATA,sha256=MY9WTWMv3sau6yXUUPC0D4AXP12sq2_PsX4Fq6-kGoQ,62977
-pyg_nightly-2.7.0.dev20250211.dist-info/RECORD,,
+pyg_nightly-2.7.0.dev20250213.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
+pyg_nightly-2.7.0.dev20250213.dist-info/METADATA,sha256=KMYn4w4Bn5To5C_3fCsn61FLL62Iz10xQk493Q4OeCE,62977
+pyg_nightly-2.7.0.dev20250213.dist-info/RECORD,,

torch_geometric/__init__.py

@@ -30,7 +30,7 @@ from .lazy_loader import LazyLoader
 contrib = LazyLoader('contrib', globals(), 'torch_geometric.contrib')
 graphgym = LazyLoader('graphgym', globals(), 'torch_geometric.graphgym')
 
-__version__ = '2.7.0.dev20250211'
+__version__ = '2.7.0.dev20250213'
 
 __all__ = [
     'Index',

torch_geometric/metrics/__init__.py

@@ -9,8 +9,11 @@ from .link_pred import (
     LinkPredMAP,
     LinkPredNDCG,
     LinkPredMRR,
+    LinkPredHitRatio,
     LinkPredCoverage,
     LinkPredDiversity,
+    LinkPredPersonalization,
+    LinkPredAveragePopularity,
 )
 
 link_pred_metrics = [
@@ -22,8 +25,11 @@ link_pred_metrics = [
     'LinkPredMAP',
     'LinkPredNDCG',
     'LinkPredMRR',
+    'LinkPredHitRatio',
     'LinkPredCoverage',
     'LinkPredDiversity',
+    'LinkPredPersonalization',
+    'LinkPredAveragePopularity',
 ]
 
 __all__ = link_pred_metrics

torch_geometric/metrics/link_pred.py

@@ -423,7 +423,12 @@ class LinkPredMetricCollection(torch.nn.ModuleDict):
 
 
 class LinkPredPrecision(LinkPredMetric):
-    r"""A link prediction metric to compute Precision @ :math:`k`.
+    r"""A link prediction metric to compute Precision @ :math:`k`, *i.e.* the
+    proportion of recommendations within the top-:math:`k` that are actually
+    relevant.
+
+    A higher precision indicates the model's ability to surface relevant items
+    early in the ranking.
 
     Args:
         k (int): The number of top-:math:`k` predictions to evaluate against.
@@ -437,7 +442,11 @@ class LinkPredPrecision(LinkPredMetric):
 
 
 class LinkPredRecall(LinkPredMetric):
-    r"""A link prediction metric to compute Recall @ :math:`k`.
+    r"""A link prediction metric to compute Recall @ :math:`k`, *i.e.* the
+    proportion of relevant items that appear within the top-:math:`k`.
+
+    A higher recall indicates the model's ability to retrieve a larger
+    proportion of relevant items.
 
     Args:
         k (int): The number of top-:math:`k` predictions to evaluate against.
@@ -472,7 +481,11 @@ class LinkPredF1(LinkPredMetric):
 
 class LinkPredMAP(LinkPredMetric):
     r"""A link prediction metric to compute MAP @ :math:`k` (Mean Average
-    Precision).
+    Precision), considering the order of relevant items within the
+    top-:math:`k`.
+
+    MAP @ :math:`k` can provide a more comprehensive view of ranking quality
+    than precision alone.
 
     Args:
         k (int): The number of top-:math:`k` predictions to evaluate against.
@@ -493,6 +506,10 @@ class LinkPredNDCG(LinkPredMetric):
     r"""A link prediction metric to compute the NDCG @ :math:`k` (Normalized
     Discounted Cumulative Gain).
 
+    In particular, can account for the position of relevant items by
+    considering relevance scores, giving higher weight to more relevant items
+    appearing at the top.
+
     Args:
         k (int): The number of top-:math:`k` predictions to evaluate against.
         weighted (bool, optional): If set to :obj:`True`, assumes sorted lists
@@ -549,7 +566,8 @@ class LinkPredNDCG(LinkPredMetric):
 
 class LinkPredMRR(LinkPredMetric):
     r"""A link prediction metric to compute the MRR @ :math:`k` (Mean
-    Reciprocal Rank).
+    Reciprocal Rank), *i.e.* the mean reciprocal rank of the first correct
+    prediction (or zero otherwise).
 
     Args:
         k (int): The number of top-:math:`k` predictions to evaluate against.
@@ -564,9 +582,28 @@ class LinkPredMRR(LinkPredMetric):
         return (pred_rel_mat / arange).max(dim=-1)[0]
 
 
+class LinkPredHitRatio(LinkPredMetric):
+    r"""A link prediction metric to compute the hit ratio @ :math:`k`, *i.e.*
+    the percentage of users for whom at least one relevant item is present
+    within the top-:math:`k` recommendations.
+
+    A high ratio signifies the model's effectiveness in satisfying a broad
+    range of user preferences.
+    """
+    higher_is_better: bool = True
+    weighted: bool = False
+
+    def _compute(self, data: LinkPredMetricData) -> Tensor:
+        pred_rel_mat = data.pred_rel_mat[:, :self.k]
+        return pred_rel_mat.max(dim=-1)[0].to(torch.get_default_dtype())
+
+
 class LinkPredCoverage(_LinkPredMetric):
     r"""A link prediction metric to compute the Coverage @ :math:`k` of
-    predictions.
+    predictions, *i.e.* the percentage of unique items recommended across all
+    users within the top-:math:`k`.
+
+    Higher coverage indicates a wider exploration of the item catalog.
 
     Args:
         k (int): The number of top-:math:`k` predictions to evaluate against.
@@ -667,3 +704,136 @@ class LinkPredDiversity(_LinkPredMetric):
     def _reset(self) -> None:
         self.accum.zero_()
         self.total.zero_()
+
+
+class LinkPredPersonalization(_LinkPredMetric):
+    r"""A link prediction metric to compute the Personalization @ :math:`k`,
+    *i.e.* the dissimilarity of recommendations across different users.
+
+    Higher personalization suggests that the model tailors recommendations to
+    individual user preferences rather than providing generic results.
+
+    Dissimilarity is defined by the average inverse cosine similarity between
+    users' lists of recommendations.
+
+    Args:
+        k (int): The number of top-:math:`k` predictions to evaluate against.
+        batch_size (int, optional): The batch size to determine how many pairs
+            of user recommendations should be processed at once.
+            (default: :obj:`2**16`)
+    """
+    higher_is_better: bool = True
+
+    def __init__(self, k: int, batch_size: int = 2**16) -> None:
+        super().__init__(k)
+        self.batch_size = batch_size
+
+        if WITH_TORCHMETRICS:
+            self.add_state('preds', default=[], dist_reduce_fx='cat')
+            self.add_state('dev_tensor', torch.empty(0), dist_reduce_fx='sum')
+        else:
+            self.preds: List[Tensor] = []
+            self.register_buffer('dev_tensor', torch.empty(0))
+
+    def update(
+        self,
+        pred_index_mat: Tensor,
+        edge_label_index: Union[Tensor, Tuple[Tensor, Tensor]],
+        edge_label_weight: Optional[Tensor] = None,
+    ) -> None:
+        # NOTE Move to CPU to avoid memory blowup.
+        self.preds.append(pred_index_mat[:, :self.k].cpu())
+
+    def compute(self) -> Tensor:
+        device = self.dev_tensor.device
+        score = torch.tensor(0.0, device=device)
+        total = torch.tensor(0, device=device)
+
+        if len(self.preds) == 0:
+            return score
+
+        pred = torch.cat(self.preds, dim=0)
+
+        if pred.size(0) == 0:
+            return score
+
+        # Calculate all pairs of nodes (e.g., triu_indices with offset=1).
+        # NOTE We do this in chunks to avoid memory blow-up, which leads to a
+        # more efficient but trickier implementation.
+        num_pairs = (pred.size(0) * (pred.size(0) - 1)) // 2
+        offset = torch.arange(pred.size(0) - 1, 0, -1, device=device)
+        rowptr = cumsum(offset)
+        for start in range(0, num_pairs, self.batch_size):
+            end = min(start + self.batch_size, num_pairs)
+            idx = torch.arange(start, end, device=device)
+
+            # Find the corresponding row:
+            row = torch.searchsorted(rowptr, idx, right=True) - 1
+            # Find the corresponding column:
+            col = idx - rowptr[row] + (pred.size(0) - offset[row])
+
+            left = pred[row.cpu()].to(device)
+            right = pred[col.cpu()].to(device)
+
+            # Use offset to work around applying `isin` along a specific dim:
+            i = max(left.max(), right.max()) + 1  # type: ignore
+            i = torch.arange(0, i * row.size(0), i, device=device).view(-1, 1)
+            isin = torch.isin(left + i, right + i)
+
+            # Compute personalization via average inverse cosine similarity:
+            cos = isin.sum(dim=-1) / pred.size(1)
+            score += (1 - cos).sum()
+            total += cos.numel()
+
+        return score / total
+
+    def _reset(self) -> None:
+        self.preds = []
+
+
+class LinkPredAveragePopularity(_LinkPredMetric):
+    r"""A link prediction metric to compute the Average Recommendation
+    Popularity (ARP) @ :math:`k`, which provides insights into the model's
+    tendency to recommend popular items by averaging the popularity scores of
+    items within the top-:math:`k` recommendations.
+
+    Args:
+        k (int): The number of top-:math:`k` predictions to evaluate against.
+        popularity (torch.Tensor): The popularity of every item in the training
+            set, *e.g.*, the number of times an item has been rated.
+    """
+    higher_is_better: bool = False
+
+    def __init__(self, k: int, popularity: Tensor) -> None:
+        super().__init__(k)
+
+        if WITH_TORCHMETRICS:
+            self.add_state('accum', torch.tensor(0.), dist_reduce_fx='sum')
+            self.add_state('total', torch.tensor(0), dist_reduce_fx='sum')
+        else:
+            self.register_buffer('accum', torch.tensor(0.))
+            self.register_buffer('total', torch.tensor(0))
+
+        self.popularity: Tensor
+        self.register_buffer('popularity', popularity)
+
+    def update(
+        self,
+        pred_index_mat: Tensor,
+        edge_label_index: Union[Tensor, Tuple[Tensor, Tensor]],
+        edge_label_weight: Optional[Tensor] = None,
+    ) -> None:
+        pred_index_mat = pred_index_mat[:, :self.k]
+        popularity = self.popularity[pred_index_mat]
+        popularity = popularity.to(self.accum.dtype).mean(dim=-1)
+        self.accum += popularity.sum()
+        self.total += popularity.numel()
+
+    def compute(self) -> Tensor:
+        if self.total == 0:
+            return torch.zeros_like(self.accum)
+        return self.accum / self.total
+
+    def _reset(self) -> None:
+        self.accum.zero_()
+        self.total.zero_()