Updated docs, added PGS5Interval

Markus28 · Markus28 · commit 16deea97ddf3 · 2025-08-08T11:12:31.000+02:00
diff --git a/docs/api_reference/metrics/interface.md b/docs/api_reference/metrics/interface.md
@@ -16,7 +16,10 @@ We implement the following metrics:
 - [VUN](../../metrics/vun.md) - Validity, Uniqueness, Novelty
 - [Fréchet Distance](frechet.md) - Optimal transport distance between fitted Gaussians
 
-## Interface Protocols
+Metrics that perform uncertainty quantification may return a [`MetricInterval`][polygraph.metrics.base.MetricInterval] object.
+
+
+## Metric Interface
 
 ::: polygraph.metrics.base.GenerationMetric
     options:
@@ -34,3 +37,12 @@ We implement the following metrics:
         show_full_path: true
         show_source: false
         heading_level: 3
+
+## Uncertainty Quantification
+
+::: polygraph.metrics.base.MetricInterval
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
diff --git a/docs/api_reference/metrics/polygraphscore.md b/docs/api_reference/metrics/polygraphscore.md
@@ -9,18 +9,25 @@
         heading_level: 2
         members: []
 
-## Estimating Distances with a Single Descriptor
+## PolyGraphScore
 
-::: polygraph.metrics.base.ClassifierMetric
+::: polygraph.metrics.base.PolyGraphScore
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
+
+::: polygraph.metrics.base.PolyGraphScoreInterval
     options:
         show_root_heading: true
         show_full_path: true
         show_source: false
         heading_level: 3
 
-## Combining Descriptors
+## Estimating Distances with a Single Descriptor
 
-::: polygraph.metrics.base.PolyGraphScore
+::: polygraph.metrics.base.ClassifierMetric
     options:
         show_root_heading: true
         show_full_path: true
diff --git a/docs/datasets/molecules.md b/docs/datasets/molecules.md
diff --git a/docs/metrics/pgs5.md b/docs/metrics/pgs5.md
@@ -0,0 +1,67 @@
+# 5-Descriptor PolyGraphScore
+
+::: polygraph.metrics.polygraphscore
+    options:
+        show_root_heading: false
+        show_full_path: false
+        show_root_toc_entry: false
+        show_source: false
+        heading_level: 2
+        members: []
+
+
+## PGS5
+
+::: polygraph.metrics.PGS5
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
+        members: [compute]
+
+::: polygraph.metrics.PGS5Interval
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
+        members: [compute]
+
+
+## Individual Classifier Metrics
+
+::: polygraph.metrics.polygraphscore.ClassifierOrbitMetric
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
+
+::: polygraph.metrics.polygraphscore.ClassifierDegreeMetric
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
+
+::: polygraph.metrics.polygraphscore.ClassifierClusteringMetric
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
+
+::: polygraph.metrics.polygraphscore.ClassifierSpectralMetric
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
+
+::: polygraph.metrics.polygraphscore.GraphNeuralNetworkClassifierMetric
+    options:
+        show_root_heading: true
+        show_full_path: true
+        show_source: false
+        heading_level: 3
diff --git a/docs/metrics/vun.md b/docs/metrics/vun.md
@@ -1,5 +1,15 @@
 # Validity, Uniqueness, Novelty
 
+::: polygraph.metrics.vun
+    options:
+        show_root_heading: false
+        show_full_path: false
+        show_root_toc_entry: false
+        show_source: false
+        heading_level: 2
+        members: []
+
+
 ::: polygraph.metrics.VUN
     options:
         show_root_heading: true
diff --git a/docs/tutorials/custom_metrics.md b/docs/tutorials/custom_metrics.md
@@ -2,6 +2,6 @@
 
 ## Custom Graph Descriptors
 
-## Custom Graph Kernels
+## Building MMD Metrics
 
-## Building Benchmarks
+## Building PolyGraphScore Metrics
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -27,14 +27,14 @@ nav:
       - Graph Descriptors: api_reference/utils/graph_descriptors.md
       - Graph Kernels: api_reference/utils/graph_kernels.md
   - Standardized Metrics:
+    - PGS5: metrics/pgs5.md
     - Gaussian TV MMD: metrics/gaussian_tv_mmd.md
     - RBF MMD: metrics/rbf_mmd.md
     - VUN: metrics/vun.md
   - Datasets:
     - Small Synthetic Datasets: datasets/small_synthetic.md
     - Procedural Datasets: datasets/procedural.md
     - Real-World Datasets: datasets/real_world_topologies.md
-    - Molecule Datasets: datasets/molecules.md
   - Utils:
     - Graph Descriptors: utils/descriptors.md
     - Graph Kernels: utils/kernels.md
diff --git a/polygraph/metrics/__init__.py b/polygraph/metrics/__init__.py
@@ -1,5 +1,5 @@
 from .base import MetricCollection
-from .polygraphscore import PGS5
+from .polygraphscore import PGS5, PGS5Interval
 from .gaussian_tv_mmd import (
     MMD2CollectionGaussianTV,
     MMD2IntervalCollectionGaussianTV,
@@ -11,6 +11,7 @@
     "VUN",
     "MetricCollection",
     "PGS5",
+    "PGS5Interval",
     "MMD2CollectionGaussianTV",
     "MMD2IntervalCollectionGaussianTV",
     "MMD2CollectionRBF",
diff --git a/polygraph/metrics/base/interface.py b/polygraph/metrics/base/interface.py
@@ -1,7 +1,7 @@
 """
 PolyGraph implements metrics that provide either a single estimate or an interval to quantify uncertainty.
-While the arguments to these metrics and their return types vary, we provide a minimal common interface here
-as the protocol [`GenerationMetric`][polygraph.metrics.base.GenerationMetric].
+We provide a minimal common interface for metrics as the protocol [`GenerationMetric`][polygraph.metrics.base.GenerationMetric].
+The only requirement to satisfy this interface is to implement a `compute` method that accepts a collection of NetworkX graphs.
 
 Metrics that implement this interface may be evaluated jointly using the [`MetricCollection`][polygraph.metrics.base.MetricCollection] class.
 
diff --git a/polygraph/metrics/base/metric_interval.py b/polygraph/metrics/base/metric_interval.py
@@ -3,7 +3,15 @@
 
 
 class MetricInterval:
-    """Class for representing uncertainty quantifications of a metric."""
+    """Class for representing uncertainty quantifications of a metric.
+
+    Attributes:
+        mean: Mean of the metric samples.
+        std: Standard deviation of the metric samples.
+        low: Lower bound of the metric interval, if `coverage` is provided.
+        high: Upper bound of the metric interval, if `coverage` is provided.
+        coverage: Coverage of the metric interval. If `None`, no bounds are computed, only the mean and standard deviation are set.
+    """
 
     def __init__(
         self,
@@ -32,6 +40,12 @@ def __init__(
     def from_samples(
         cls, samples: np.ndarray, coverage: Optional[float] = None
     ):
+        """Create a `MetricInterval` from a collection of samples.
+
+        Args:
+            samples: 1D array of samples.
+            coverage: Coverage of the interval. If `None`, no bounds are computed, only the mean and standard deviation are set.
+        """
         if samples.ndim != 1:
             raise ValueError("Samples must be a 1D array")
 
diff --git a/polygraph/metrics/base/polygraphscore.py b/polygraph/metrics/base/polygraphscore.py
@@ -1,8 +1,41 @@
-"""PolyGraphScores to compare graph distributions.
-
+"""
 PolyGraphScores compare generated graphs to reference graphs by fitting a binary classifier to discriminate between the two.
 Performance metrics of this classifier lower-bound intrinsic probability metrics.
 Multiple graph descriptors may be combined within PolyGraphScores to yield a theoretically grounded summary metric.
+
+Either logistic regression or TabPFN may be used for classification.
+The classifiers may be then be evaluated by:
+
+- Data log-likelihood - Provides a lower bound on the Jensen-Shannon distance, or
+- Informedness - Provides a lower bound on the total variation distance.
+
+The [`PolyGraphScore`][polygraph.metrics.base.polygraphscore.PolyGraphScore] class combines metrics across multiple graph descriptors,
+providing the tightest lower-bound on the probability metrics.
+The [`ClassifierMetric`][polygraph.metrics.base.polygraphscore.ClassifierMetric] class, on the other hand, computes a lower bound
+for a single graph descriptor.
+
+The [`PolyGraphScoreInterval`][polygraph.metrics.base.polygraphscore.PolyGraphScoreInterval] class implements a variant of the PolyGraphScore
+with uncertainty quantification.
+
+Example:
+    ```python
+    from polygraph.datasets import PlanarGraphDataset, SBMGraphDataset
+    from polygraph.metrics.base import PolyGraphScore
+    from polygraph.utils.graph_descriptors import OrbitCounts, SparseDegreeHistogram
+
+    reference = PlanarGraphDataset("val").to_nx()
+    generated = SBMGraphDataset("val").to_nx()
+
+    benchmark = PolyGraphScore(
+        reference,
+        descriptors={
+            "orbit": OrbitCounts(),
+            "degree": SparseDegreeHistogram(),
+        },
+    )
+    print(benchmark.compute(generated))         # {'polygraphscore': 0.9975117559449073, 'polygraphscore_descriptor': 'degree', 'subscores': {'orbit': 0.9962500491652303, 'degree': 0.9975117559449073}}
+    ```
+
 """
 
 from typing import (
@@ -403,7 +436,7 @@ def compute(
 
 
 class PolyGraphScore(GenerationMetric):
-    """PolyGraphScore to compare graph distributions.
+    """PolyGraphScore to compare graph distributions, combining multiple graph descriptors.
 
     Args:
         reference_graphs: Reference graphs
@@ -438,7 +471,7 @@ def compute(
             generated_graphs: Generated graphs
 
         Returns:
-            Dictionary of scores.
+            Typed dictionary of scores.
                 The key `"polygraphscore"` specifies the PolyGraphScore, giving the estimated tightest lower-bound on the probability metric.
                 The key `"polygraphscore_descriptor"` specifies the descriptor that achieves this bound.
                 All descritor-wise scores are returned in the key `"subscores"`.
@@ -462,6 +495,17 @@ def compute(
 
 
 class PolyGraphScoreInterval(GenerationMetric):
+    """Uncertainty quantification for [`PolyGraphScore`][polygraph.metrics.base.polygraphscore.PolyGraphScore].
+
+    Args:
+        reference_graphs: Reference graphs. Must provide at least `2 * subsample_size` graphs.
+        descriptors: Dictionary of descriptor names and descriptor functions
+        subsample_size: Size of each subsample, should be consistent with the number
+            of reference and generated graphs passed to [`PolyGraphScore`][polygraph.metrics.base.polygraphscore.PolyGraphScore]
+            for point estimates.
+        num_samples: Number of samples to draw for uncertainty quantification.
+    """
+
     _variant: Literal["informedness", "jsd"]
     _classifier: Literal["logistic", "tabpfn"]
 
@@ -474,6 +518,11 @@ def __init__(
         variant: Literal["informedness", "jsd"] = "jsd",
         classifier: Literal["logistic", "tabpfn"] = "tabpfn",
     ):
+        if len(reference_graphs) < 2 * subsample_size:
+            raise ValueError(
+                "Number of reference graphs must be at least 2 * subsample_size"
+            )
+
         self._sub_metrics = {
             name: _ClassifierMetricSamples(
                 reference_graphs, descriptors[name], variant, classifier
@@ -487,6 +536,21 @@ def compute(
         self,
         generated_graphs: Collection[nx.Graph],
     ) -> PolyGraphScoreIntervalResult:
+        """Compute the PolyGraphScoreInterval.
+
+        Args:
+            generated_graphs: Generated graphs. Must provide at least `2 * subsample_size` graphs.
+
+        Returns:
+            Typed dictionary of scores.
+                The key `"polygraphscore"` specifies the PolyGraphScore, giving mean and standard deviation as [`MetricInterval`][polygraph.metrics.base.metric_interval.MetricInterval] objects.
+                The key `"polygraphscore_descriptor"` describes which descriptors achieve this score. This is a dictionary mapping descriptor names to the ratio of samples in which the descriptor was chosen.
+                All descritor-wise scores are returned in the key `"subscores"`. These are [`MetricInterval`][polygraph.metrics.base.metric_interval.MetricInterval] objects.
+        """
+        if len(generated_graphs) < 2 * self._subsample_size:
+            raise ValueError(
+                "Number of generated graphs must be at least 2 * subsample_size"
+            )
         all_sub_samples = {
             name: metric.compute(
                 generated_graphs, self._subsample_size, self._num_samples
diff --git a/polygraph/metrics/polygraphscore.py b/polygraph/metrics/polygraphscore.py
diff --git a/polygraph/metrics/vun.py b/polygraph/metrics/vun.py
diff --git a/scripts/griffe_extension.py b/scripts/griffe_extension.py
diff --git a/tests/test_polygraphscore.py b/tests/test_polygraphscore.py
