tdaphantom 1.0.0__py3-none-any.whl

tdaphantom/__init__.py

@@ -0,0 +1,2 @@
+
+from .tdaphantom import Phantom

tdaphantom/hypothesis_tests/bottleneck_distance_tests/bottleneck_distance_test.py

@@ -0,0 +1,190 @@
+import numpy as np
+from typing import List, Optional
+import math
+import random
+import gudhi
+from scipy.spatial.distance import cdist
+from tdaphantom.metrics.metrics import w_infinity, hausdorff_dist_matrix, hausdorff
+
+
+class BNTest:
+    def __init__(
+        self,
+        point_cloud:         np.ndarray,
+        is_distance_matrix:  bool = False,
+        dgm:                 np.ndarray = None,
+        k:                   int = 1,
+        alpha:               float = 0.05,
+        complex:             str = "VR",
+        max_depth:           int = 50,  # low and slow
+        method: str = "bottleneck:subsample"
+    ):
+        """
+        The bottleneck hypothesis testing from
+        'confidence sets for persistence diagrams'
+        by Fasy et al
+        """
+        self.method = method
+        self.method_calls = {
+            "bottleneck:subsample": self.subsample,
+            "bottleneck:concentration": self.concentration,
+            "bottleneck:shells": self.shells,
+            "bottleneck:density": self.density
+        }
+        self.pc = point_cloud
+        self.dgm = dgm
+        self.is_distance_matrix = is_distance_matrix
+        self.k = k
+        self.complex = complex  # currently only VR is supported
+        self.max_depth = max_depth
+        self.alpha = alpha
+
+    def _subsampling_method_via_persistence(self, subsample_percentage: float = 0.3) -> float:
+        """
+        DEPRECIATED - DO NOT USE
+        E[W_infnity(hat(P),P)] != E[W_infnity(hat(P),subsample_hat(P)]
+        """
+
+        n = len(self.dgm)
+        b = int(0.4*n)
+        try:
+            N = min(int(subsample_percentage * math.comb(n, b)), self.max_depth)
+        except OverflowError:
+            N = self.max_depth
+
+        T_j_array = np.zeros(N)
+        for i in range(N):
+            idx = np.random.choice(n, size=b, replace=False)
+            subsample = self.dgm[idx]
+            T_j_array[i] = self.w_infinity(subsample, self.dgm)
+
+    def _subsampling_method(self, subsample_percentage: float = 0.8) -> np.ndarray:
+        """
+        Fasy et al. 4.1 subsampling
+        b   = subsample size = O(n / log(n))
+        N   = number of subsamples (theory uses n choose b, but we will use a subset)
+        A bar with persistence > C_b is significant at level alpha.
+        By the bottleneck stability theorem, W_inf(PH(S_n), PH(P)) <= C_b
+        with probability >= 1 - alpha.
+
+        From the paper:
+        P(H(S_n, M) > C_n) <= alpha + O((b/n)^(1/4))
+
+        The bias term O((b/n)^(1/4)) -> 0 as b/n -> 0, so theory requires b << n.
+        The paper uses b = O(n / log(n)) for the theoretical guarantee.
+        In practice, larger b gives smaller c_n and more power but looser theory guarantees.
+        """
+        n = len(self.pc)
+        b = min(int(3.5*(n / np.log(n))), int(0.8*n))
+        try:
+            N = min(int(subsample_percentage * math.comb(n, b)), self.max_depth)
+        except OverflowError:
+            N = self.max_depth
+        all_idx = np.arange(n)
+
+        if not self.is_distance_matrix:
+            D = cdist(self.pc, self.pc)
+        else:
+            D = self.pc
+
+        T_j_array = np.zeros(N)
+        for i in range(N):
+            idx = np.random.choice(n, size=b, replace=False)
+            # h(S_n, S_b*) = max_{i in S_n} min_{j in S_b*} D[i,j]
+            T_j_array[i] = float(D[:, idx].min(axis=1).max())
+
+        # bias_order = (b/n)**(0.25)
+
+        return T_j_array
+
+    def subsample(self):
+        """
+        Calls subsampling method to calculate c_n and p_values
+        """
+        births = self.dgm[:, 0]
+        deaths = self.dgm[:, 1]
+        pers = deaths - births
+        T_j_array = self._subsampling_method()
+        c_n = float(np.quantile(T_j_array, 1.0 - self.alpha))
+        p_values = np.array([
+            float(np.mean(T_j_array >= p / 2)) for p in pers
+        ])
+        return c_n, p_values
+
+    def concentration_of_measure_method(self):
+        """
+        Fasy et al. 4.2 concentration of measure
+
+        From the paper:
+        P(H(S_n, M) > \hat(t_n)) <= alpha + O((log(n)/n)^(1/(2+d)))
+        """
+
+        ...
+
+    def concentration(self):
+        """
+        Calls concentration method to calculate c_n
+        """
+        c_n = self.concentration_of_measure_method()
+        return c_n, None
+
+    def shells_method(self):
+        """
+        Fasy et al. 4.3 method of shells
+
+        From the paper:
+        P(H(S_{2,n}, M) > \hat(t_{1,n}) <= alpha + O(r_n)
+        """
+        ...
+
+    def shells(self):
+        """
+        Calls shells method to calculate c_n
+        """
+        c_n = self.shells_method()
+        return c_n, None
+
+    def denisty_method(self):
+        """
+        Fasy et al. 4.4 Density estimation
+
+        From the paper:
+        P(||\hat{p}_h - p_h||_infinity > Z_alpha / sqrt(nh^D) ) <= alpha + O(log(n)/nh^D)^((4+D)/(4+2D))
+        """
+        ...
+
+    def denisty(self):
+        """
+        Calls shells method to calculate c_n
+        """
+        c_n = self.density_method()
+        return c_n, None
+
+    def results(self) -> dict:
+        """
+        Returns a structured array with one row per bar.
+        Cols: birth, death, pers, p_value, significant
+
+        and the threshold c_n
+        """
+        c_n = -np.inf
+        p_values = None
+        if self.method in self.method_calls.keys():
+            c_n, p_values = self.method_calls[self.method]()
+
+        births = self.dgm[:, 0]
+        deaths = self.dgm[:, 1]
+        pers = deaths - births
+
+        rejected = pers > 2*c_n
+
+        return {
+            "results_array": np.column_stack([
+                births,
+                deaths,
+                pers,
+                p_values,
+                rejected.astype(float),
+            ]),
+            "threshold": 2*c_n  # used for diagram
+        }

tdaphantom/hypothesis_tests/universal_null_tests/universal_null_hypothesis_test.py

@@ -0,0 +1,236 @@
+import numpy as np
+from typing import List
+import warnings
+
+EULER_MASCHERONI = 0.57721566490153
+
+
+class UNTest:
+    def __init__(
+        self,
+        dgm:                 np.ndarray,
+        k:                   int,
+        alpha:               float = 0.05,
+        complex:             str = "VR",
+        correction_strategy: str = "BH",
+        max_depth:           int = 1000,
+        max_threshold=None,
+        method: str = "universal_null:median"
+    ):
+        """
+        Implimentation of the universal null hypothesis test from
+        'A universal null‑distribution for topological data analysis'
+        by Omer Bobrowski & Primoz Skraba
+        """
+        self.dgm = np.copy(dgm)
+        self.k = k
+        self.complex = complex  # currently only VR is supported
+        self.max_depth = max_depth
+        self.alpha = alpha
+        self.correction_strategy = correction_strategy
+        self.method = method
+
+        default_max = 10.0  # max epsilon for ripser for example
+
+        if max_threshold is not None:
+            self.max_threshold = max_threshold
+        else:
+            finite_deaths = self.dgm[np.isfinite(self.dgm[:, 1]), 1]
+            self.max_threshold = float(
+                np.max(finite_deaths))*10 if len(finite_deaths) > 0 else default_max
+            warnings.warn(
+                "max_threshold not supplied — falling back to max finite death * 10. "
+                "Pass max_eps from your Rips filtration for correct results.",
+                UserWarning,
+            )
+
+        self.A = None
+        if self.complex == "VR":
+            self.A = 1  # for Vietoris-Rips complex
+        elif self.complex == "C":
+            self.A = 0.5
+        else:
+            raise ValueError(
+                f"Unknown complex type {self.complex}. Use 'VR' or 'C'.")
+
+        finite_mask = np.isfinite(self.dgm[:, 1])
+        births_f = self.dgm[finite_mask, 0]
+        pi_values_f = self.dgm[finite_mask, 1] / births_f
+
+        valid = (births_f > 0) & (pi_values_f > 1.0)
+        log_log_pi = np.log(np.log(pi_values_f[valid]))
+
+        if self.method == "universal_null:median":
+            self.L_hat = float(np.median(log_log_pi))
+        elif self.method == "universal_null:mean":
+            self.L_hat = float(np.mean(log_log_pi))
+
+    def _correct_alpha(self) -> float:
+        if self.correction_strategy == "Bonferroni":
+            return self.alpha / len(self.dgm)
+        elif self.correction_strategy == "BH":
+            return self.alpha
+        elif self.correction_strategy == None:
+            return self.alpha
+        else:
+            raise ValueError(
+                f"Unknown multiple testing correction strategy "
+                f"{self.correction_strategy}. Use 'Bonferroni' or 'BH'."
+            )
+
+    def _pi_min(self, x: float) -> float:
+        """
+        minimum death/birth ratio such that the p-value for this diagram is under x
+        """
+        if x <= 0.0:
+            return np.inf
+        if x >= 1.0:
+            return 1.0
+
+        B = -EULER_MASCHERONI - self.A * self.L_hat
+        l_thresh = np.log(-np.log(x))
+        return float(np.exp(np.exp((l_thresh - B) / self.A)))
+
+    def _find_threshold_for_infinite_cycles(self, t_0: float) -> float:
+        """
+        This algorithm gives us the threshold we need to use when calculating p_values
+        for infinite cycles
+        We choose the earliest-born infinite cycle (min(I)),
+        while we could have chosen the latest-born (max(I)), or any intermediate value.
+        This choice represents  trade-off between the number of iterations needed and the overestimation of τ.
+        Choosing the earliest born cycle results in the smallest threshold, but with potentially more iterations, while choosing the last cycle will
+        have fewer iterations with a possible overestimation of the threshold.
+        """
+        tau = t_0
+        i = 0
+
+        while i < self.max_depth:
+            i += 1
+            D = self.dgm[self.dgm[:, 0] <= tau]
+            if len(D) == 0:
+                break
+
+            threshold = self._pi_min(self.alpha / len(D))
+            inf_births = D[D[:, 1] >= tau, 0]
+            inf_births = inf_births[inf_births > 0]
+
+            if len(inf_births) == 0:
+                break
+
+            I_births = inf_births[tau / inf_births < threshold]
+
+            if len(I_births) == 0:
+                break
+
+            tau = float(np.min(I_births) * threshold)
+
+        return tau
+
+    def _calculate_l(self) -> np.ndarray:
+        """
+        Normalises the persistence diagram values so the noise values follow
+        the Lgumbel(0,1) distribution
+
+        l_value is defined piecewise
+        for finite death it is defined using a log(log()) transform and normalised
+        for infinite death values we let death = max_threshold
+        """
+
+        births = self.dgm[:, 0]
+        deaths = np.where(np.isfinite(
+            self.dgm[:, 1]), self.dgm[:, 1], self.max_threshold)
+        pi_values = deaths / births
+
+        tau = self._find_threshold_for_infinite_cycles(self.max_threshold)
+        inf_mask = ~np.isfinite(self.dgm[:, 1])
+        pi_values[inf_mask] = tau / births[inf_mask]
+
+        log_log_pi = np.full(len(self.dgm), np.nan)
+        valid = (births > 0) & (pi_values > 1.0)
+        log_log_pi[valid] = np.log(np.log(pi_values[valid]))
+
+        l_values = self.A * log_log_pi - EULER_MASCHERONI - self.A * self.L_hat
+        return l_values
+
+    def _calculate_p_values_for_persistence_diagram(self) -> np.ndarray:
+        """
+        Finds the p value for each cycle.
+        l_values for infinite cycles are handeled by _calculate_l
+        """
+        l_values = self._calculate_l()
+        p_values = np.exp(-np.exp(l_values))
+        self.p_values = p_values
+        return p_values
+
+    def calculate_significance_for_persistence_diagram(self) -> np.ndarray:
+        """
+        This actually applies your corrected alpha to check which p are significant
+        """
+        p_values = self._calculate_p_values_for_persistence_diagram()
+
+        if self.correction_strategy == "Bonferroni":
+            rejected = p_values < self._correct_alpha()
+
+        elif self.correction_strategy == "BH":
+            # sort p-values, find largest k where p_(k) <= k/m * alpha
+            m = len(p_values)
+            order = np.argsort(p_values)
+            sorted_p = p_values[order]
+            bh_line = (np.arange(1, m + 1) / m) * self.alpha
+            below = np.where(sorted_p <= bh_line)[0]
+            rejected = np.zeros(m, dtype=bool)
+            if len(below) > 0:
+                rejected[order[:below[-1] + 1]] = True
+        elif self.correction_strategy == None:
+            rejected = p_values < self.alpha
+        else:
+            raise ValueError(
+                f"Unknown multiple testing correction strategy "
+                f"{self.correction_strategy}. Use 'Bonferroni' or 'BH'."
+            )
+
+        return rejected
+
+    def results(self) -> dict:
+        """
+        Returns a structured array with one row per bar.
+        Cols: birth, death, pi, p_value, significant
+        """
+        rejected = self.calculate_significance_for_persistence_diagram()
+        p_values = self.p_values
+
+        births = self.dgm[:, 0]
+        deaths = self.dgm[:, 1]
+        pi_values = np.where(
+            np.isfinite(deaths),
+            deaths / births,
+            self.max_threshold / births,
+        )
+
+        if self.correction_strategy == "Bonferroni":
+            alpha_thresh = self._correct_alpha()
+        elif self.correction_strategy == "BH":
+            # alpha_thresh = k/m * alpha where k = number of rejections
+            # this is the BH threshold that was actually applied
+            m = len(p_values)
+            k = int(rejected.sum())
+            print(f"m: {m}, k - number of rejections: {k}")
+            if k > 0:
+                alpha_thresh = (k / m) * self.alpha
+            else:
+                alpha_thresh = 0.0   # nothing rejected, threshold is below all bars
+        elif self.correction_strategy == None:
+            alpha_thresh = self.alpha
+
+        threshold = self._pi_min(alpha_thresh)
+
+        return {
+            "results_array": np.column_stack([
+                births,
+                deaths,
+                pi_values,
+                p_values,
+                rejected.astype(float),
+            ]),
+            "threshold": threshold,
+        }

tdaphantom/metrics/metrics.py

@@ -0,0 +1,79 @@
+import gudhi
+import numpy as np
+import random
+from scipy.spatial.distance import cdist
+
+
+def w_infinity(dgm_1: np.ndarray, dgm_2: np.ndarray) -> float:
+    w_inf_approx = gudhi.bottleneck_distance(
+        dgm_1.tolist(), dgm_2.tolist(), e=0.01)
+    return w_inf_approx
+
+
+def hausdorff_directed(A: np.ndarray, B: np.ndarray) -> float:
+    """
+    Directed Hausdorff distance from Algorithm 2 in "An Efficient Algorithm for Calculating the Exact Hausdorff Distance"
+    from Taha & Hanbury
+    """
+    rng = np.random.default_rng()
+    A = rng.permutation(A)
+    B = rng.permutation(B)
+
+    c_max = 0.0
+    for a in A:
+        c_min = np.inf
+        for b in B:
+            d = float(np.linalg.norm(a - b))
+            if d < c_max:
+                c_min = d  # paper omits this but it seems required
+                break
+            if d < c_min:
+                c_min = d
+        if c_min > c_max:
+            c_max = c_min
+
+    return c_max
+
+
+def hausdorff(A: np.ndarray, B: np.ndarray) -> float:
+    """
+    Symmetric Hausdorff distance
+    """
+    return max(hausdorff_directed(A, B), hausdorff_directed(B, A))
+
+
+def hausdorff_directed_dist_matrix(A: np.ndarray, B: np.ndarray) -> float:
+    """
+    Taken from "an Efficient Algorithm for Calculating the Exact Hausdorff Distance"
+    by Abdel Aziz Taha and Allan Hanbury.
+
+    This does not need to compute euclidean distance as this is done for us
+    """
+    rng = np.random.default_rng()
+    A_idx = rng.permutation(A_idx)
+    B_idx = rng.permutation(B_idx)
+
+    c_max = 0.0
+    for i in A_idx:
+        c_min = np.inf
+        for j in B_idx:
+            d = float(A[i, j])
+            if d < c_max:
+                c_min = d
+                break
+            if d < c_min:
+                c_min = d
+        if c_min > c_max:
+            c_max = c_min
+
+    return c_max
+
+
+def hausdorff_dist_matrix(A_idx: np.ndarray, B_idx: np.ndarray) -> float:
+    """
+    Symmetric Hausdorff distance H(A,B) = max(h(A,B), h(B,A))
+    """
+    return max(
+        hausdorff_directed_dist_matrix(A_idx, B_idx),
+        hausdorff_directed_dist_matrix(B_idx, A_idx),
+    )

tdaphantom/tdaphantom.py

@@ -0,0 +1,606 @@
+import numpy as np
+import warnings
+from tdaphantom.hypothesis_tests.universal_null_tests.universal_null_hypothesis_test import UNTest
+from tdaphantom.hypothesis_tests.bottleneck_distance_tests.bottleneck_distance_test import BNTest
+import matplotlib.pyplot as plt
+import gudhi
+from ripser import ripser
+import pickle
+import os
+
+
+class Phantom:
+    """
+    Persistence diagram container.
+
+    point_cloud : np.ndarray
+        Either an (n, d) point cloud or an (n, n) distance matrix.
+
+    is_distance_matrix : bool
+        Set True when point_cloud is a distance matrix.
+
+    dgms : dict[int, np.ndarray]
+        Persistence diagrams keyed by homological dimension.
+        Each value has shape (n, 2) — columns are [birth, death].
+        Populated by calculate_dgms_from_point_cloud.
+    """
+
+    def __init__(
+        self,
+        point_cloud: np.ndarray,
+        is_distance_matrix: bool = False,
+    ):
+        self.pc: np.ndarray = point_cloud
+        self.is_dist: bool = is_distance_matrix
+        self.dgms: dict[int, np.ndarray] = {}
+        self._cached_results: dict = {}
+        self.k: int = None
+
+        self.allowed_methods: list[str] = [
+            "universal_null",
+            "universal_null:median",
+            "universal_null:mean",
+            "bottleneck",
+            "bottleneck:subsample",
+            # "bottleneck:shells",
+            # "bottleneck:density",
+            # "bottleneck:concentration",
+        ]
+        self.allowed_methods_descriptions: dict[str, str] = {
+            "universal_null":           "Alias for universal_null:median.",
+            "universal_null:median":    "Assumes noise follows a Gumbel distribution (Bobrowski & Skraba); uses median normalisation.",
+            "universal_null:mean":      "Assumes noise follows a Gumbel distribution (Bobrowski & Skraba); uses mean normalisation.",
+            "bottleneck":               "Alias for bottleneck:subsample. All bottleneck methods aim to bound the bottleneck distance between your samples diagram and the ideal hypothetical diagram using confidence intervals. This is how the hypothesis test is designed.",
+            "bottleneck:subsample":     "Bootstrap confidence band via subsampling (Fasy et al.).",
+            # "bottleneck:shells":        "Bottleneck test using shell decomposition.",
+            # "bottleneck:density":       "Bottleneck test using density estimation.",
+            # "bottleneck:concentration": "Bottleneck test using concentration inequalities.",
+        }
+
+    def __repr__(self) -> str:
+        sizes = {k: len(v) for k, v in self.dgms.items()}
+        return (
+            f"Phantom("
+            f"n_points={len(self.pc)}, "
+            f"is_distance_matrix={self.is_dist}, "
+            f"computed_dims={list(self.dgms.keys())}, "
+            f"diagram_sizes={sizes})"
+        )
+
+    def calculate_dgms_from_point_cloud(
+        self,
+        point_cloud: np.ndarray = None,
+        is_distance_matrix: bool = None,
+        max_dim: int = None,
+        max_eps: float = None,
+        k: int = None,
+    ) -> dict[int, np.ndarray]:
+        """
+        Build a Vietoris-Rips complex and compute persistence diagrams for
+        every homological dimension 0 … max_dim.
+
+        max_dim defaults to k when provided, otherwise 1.  This lets
+        you write calculate_dgms_from_point_cloud(k=2) and have exactly
+        the diagrams needed for a subsequent hypothesis_test(k=2)
+
+        point_cloud : np.ndarray, optional
+            Overrides self.pc when provided.
+        is_distance_matrix : bool, optional
+            Overrides self.is_dist when provided.
+        max_dim : int, optional
+            Highest homological dimension to compute.
+            Defaults to k if given, otherwise 1.
+        max_eps : float, optional
+            Maximum edge length for the Rips filtration (default np.inf).
+        k : int, optional
+            Convenience alias: sets max_dim when max_dim is not
+            explicitly supplied.
+
+        Returns:
+            dict[int, np.ndarray]
+                Persistence diagrams keyed by homological dimension.
+        """
+
+        if point_cloud is None:
+            point_cloud = self.pc
+        if is_distance_matrix is None:
+            is_distance_matrix = self.is_dist
+        if max_dim is None:
+            max_dim = k if k is not None else 1
+
+        # Default max_eps to the diameter of the data (matching ripser's
+        # behaviour).  np.inf is intentionally avoided: gudhi will enumerate
+        # every possible simplex up to max_dim+1, which is O(n^(max_dim+2))
+        # and will exhaust memory on any moderately sized point cloud.
+        if max_eps is None:
+            if is_distance_matrix:
+                max_eps = float(np.max(point_cloud))
+            else:
+                # Diameter via broadcasting; O(n²) memory — warn for large inputs.
+                if len(point_cloud) > 5000:
+                    warnings.warn(
+                        f"Computing the diameter of {len(point_cloud)} points "
+                        f"requires an O(n²) distance matrix. Consider passing "
+                        f"max_eps explicitly to avoid this.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+                D = np.linalg.norm(
+                    point_cloud[:, None, :] - point_cloud[None, :, :], axis=-1
+                )
+                max_eps = float(D.max())
+
+        self.max_eps = max_eps
+
+        if is_distance_matrix:
+            rc = gudhi.RipsComplex(
+                distance_matrix=point_cloud.tolist(),
+                max_edge_length=max_eps,
+                sparse=0.3,
+            )
+        else:
+            rc = gudhi.RipsComplex(
+                points=point_cloud.tolist(),
+                max_edge_length=max_eps,
+                sparse=0.3,
+            )
+
+        # create_simplex_tree needs max_dimension = max_dim + 1 to compute
+        # homology up to degree max_dim
+        st = rc.create_simplex_tree(max_dimension=max_dim + 1)
+        st.compute_persistence()
+
+        self.dgms = {}
+        for dim in range(max_dim + 1):
+            intervals = st.persistence_intervals_in_dimension(dim)
+            if len(intervals) == 0:
+                self.dgms[dim] = np.empty((0, 2))
+            else:
+                dgm = np.array(intervals, dtype=float)
+                # Remove degenerate bars (numerical artefacts)
+                self.dgms[dim] = dgm[dgm[:, 1] > dgm[:, 0]]
+
+        return self.dgms
+
+    def calculate_dgms_from_point_cloud_ripser(
+        self,
+        point_cloud: np.ndarray = None,
+        is_distance_matrix: bool = None,
+        max_dim: int = None,
+        max_eps: float = None,
+        k: int = None,
+    ) -> dict[int, np.ndarray]:
+        """
+        Ripser backend for computing persistence diagrams.  Equivalent
+        interface to calculate_dgms_from_point_cloud but uses ripser
+        instead of gudhi's RipsComplex.
+
+        Ripser is significantly faster than gudhi for Vietoris-Rips
+        persistence, especially at higher dimensions, because it exploits
+        the implicit representation of the Rips complex and uses
+        cohomology rather than homology internally.
+
+        point_cloud : np.ndarray, optional
+            Overrides self.pc when provided.
+        is_distance_matrix : bool, optional
+            Overrides self.is_dist when provided.
+        max_dim : int, optional
+            Highest homological dimension to compute.
+            Defaults to k if given, otherwise 1.
+        max_eps : float, optional
+            Maximum edge length / filtration threshold.
+            Defaults to the diameter of the data.
+        k : int, optional
+            sets max_dim when max_dim is not
+            explicitly supplied.
+
+        Returns
+        dict[int, np.ndarray]
+            Persistence diagrams keyed by homological dimension,
+            stored in ``self.dgms``.
+        """
+        if point_cloud is None:
+            point_cloud = self.pc
+        if is_distance_matrix is None:
+            is_distance_matrix = self.is_dist
+        if max_dim is None:
+            max_dim = k if k is not None else 1
+        if max_eps is None:
+            max_eps = np.inf  # ripser handles inf safely via its internal algorithms
+
+        result = ripser(
+            point_cloud,
+            maxdim=max_dim,
+            # thresh=max_eps,
+            distance_matrix=is_distance_matrix,
+        )
+
+        self.dgms = {}
+        for dim, dgm in enumerate(result["dgms"]):
+            if len(dgm) == 0:
+                self.dgms[dim] = np.empty((0, 2))
+            else:
+                dgm = np.array(dgm, dtype=float)
+                # Remove degenerate bars (numerical artefacts)
+                self.dgms[dim] = dgm[dgm[:, 1] > dgm[:, 0]]
+
+        self.max_eps = max_eps
+        return self.dgms
+
+    def display_dgms(
+        self,
+        dgms: np.ndarray = None,
+        plot: str = "both",
+    ) -> None:
+        """
+        Plot the computed persistence diagrams.
+
+        Each homological dimension is drawn in a distinct colour.  Call
+        calculate_dgms_from_point_cloud before this method or pass in a diagram.
+
+        plot : str
+            "diagram"  — persistence diagram only (birth vs death).
+            "barcode"  — barcode only (one horizontal bar per feature).
+            "both"     — diagram and barcode side by side (default).
+        """
+        if not self.dgms:
+            if not dgms:
+                raise ValueError(
+                    "No persistence diagrams found. "
+                    "Call calculate_dgms_from_point_cloud first."
+                    "Or pass in your own diagram with the form {0: dgm_0, 1: dgm_2, ...}"
+                )
+        if plot not in ("diagram", "barcode", "both"):
+            raise ValueError(
+                f"plot must be 'diagram', 'barcode', or 'both', got {plot!r}."
+            )
+
+        dims = sorted(self.dgms.keys())
+        colours = plt.cm.tab10.colors
+
+        n_cols = 2 if plot == "both" else 1
+        fig, axes = plt.subplots(
+            1, n_cols, figsize=(6 * n_cols, 5), squeeze=False)
+
+        all_finite = np.concatenate(
+            [dgm[np.isfinite(dgm[:, 1])] for dgm in self.dgms.values()
+             if len(dgm) > 0],
+            axis=0,
+        ) if any(len(d) > 0 for d in self.dgms.values()) else np.empty((0, 2))
+
+        lim = all_finite[:, 1].max() * 1.05 if len(all_finite) else 1.0
+
+        if plot in ("diagram", "both"):
+            ax = axes[0, 0]
+            ax.plot([0, lim], [0, lim], "k--", lw=0.8,
+                    alpha=0.4, label="diagonal")
+
+            for dim in dims:
+                dgm = self.dgms[dim]
+                if len(dgm) == 0:
+                    continue
+                births = dgm[:, 0]
+                deaths = dgm[:, 1].copy()
+
+                inf_mask = ~np.isfinite(deaths)
+                deaths[inf_mask] = lim
+                colour = colours[dim % len(colours)]
+                ax.scatter(
+                    births, deaths,
+                    s=10, alpha=0.8, color=colour,
+                    label=f"H_{dim} ({len(dgm)})",
+                    zorder=3,
+                )
+
+                if inf_mask.any():
+                    ax.scatter(
+                        births[inf_mask], deaths[inf_mask],
+                        s=30, marker="^", color=colour, zorder=4,
+                    )
+
+            ax.set_xlabel("birth")
+            ax.set_ylabel("death")
+            ax.set_title("Persistence diagram")
+            ax.set_aspect("equal")
+            ax.set_xlim(0, lim)
+            ax.set_ylim(0, lim)
+            ax.legend(fontsize=8)
+
+        if plot in ("barcode", "both"):
+            ax = axes[0, 1 if plot == "both" else 0]
+
+            rank = 0
+            tick_positions = []
+            tick_labels = []
+
+            for dim in dims:
+                dgm = self.dgms[dim]
+                if len(dgm) == 0:
+                    continue
+                colour = colours[dim % len(colours)]
+
+                pers = dgm[:, 1] - dgm[:, 0]
+                order = np.argsort(pers)[::-1]
+                dim_start = rank
+
+                for idx in order:
+                    birth = dgm[idx, 0]
+                    death = dgm[idx, 1] if np.isfinite(dgm[idx, 1]) else lim
+                    ax.hlines(rank, birth, death, colors=colour,
+                              linewidth=1.5, alpha=0.8)
+                    rank += 1
+
+                mid = (dim_start + rank - 1) / 2
+                tick_positions.append(mid)
+                tick_labels.append(f"H_{dim}")
+
+            ax.set_xlabel("filtration value epsilon")
+            ax.set_yticks(tick_positions)
+            ax.set_yticklabels(tick_labels)
+            ax.set_title("Barcode")
+            ax.invert_yaxis()
+
+        plt.tight_layout()
+        plt.show()
+
+    def hypothesis_test(
+        self,
+        alpha: float = 0.05,
+        methods: list[str] = None,
+        correction_method: str = "BH",
+        k: int = 1,
+    ) -> dict:
+        """
+        Run significance tests on the persistence diagram for dimension k.
+
+        Requires calculate_dgms_from_point_cloud to have been called with
+        max_dim >= k (or equivalently k >= k).
+
+        alpha : float
+            Significance level in (0, 1).  Default 0.05.
+        methods : list[str], optional
+            One or more of self.allowed_methods.
+            Defaults to ["universal_null", "bottleneck"].
+        correction_method : str
+            Multiple-testing correction strategy passed to the test objects.
+        k : int
+            Homological dimension to test.  Default 1.
+
+        dict
+            Keyed by method name; each value is the dict returned by the
+            corresponding test's .results() method.
+        """
+        if not isinstance(k, int) or k < 0:
+            raise TypeError(
+                f"k must be a non-negative integer homological dimension, got {k!r}."
+            )
+        if not isinstance(alpha, float):
+            raise TypeError(
+                f"alpha must be a float, got {type(alpha).__name__}."
+            )
+        if alpha <= 0 or alpha >= 1:
+            raise ValueError(
+                f"alpha must be strictly between 0 and 1, got {alpha}."
+            )
+
+        if methods is None:
+            methods = ["universal_null", "bottleneck"]
+
+        invalid = [m for m in methods if m not in self.allowed_methods]
+        if invalid:
+            raise ValueError(
+                f"Unknown method(s): {invalid}. "
+                f"Allowed methods: {self.allowed_methods}."
+            )
+
+        if k not in self.dgms:
+            raise ValueError(
+                f"No persistence diagram found for dimension k={k}. "
+                f"Call calculate_dgms_from_point_cloud(k={k}) first."
+            )
+
+        self.k = k
+        dgm_k = self.dgms[k]
+        results = {}
+
+        if "universal_null" in methods or "universal_null:median" in methods:
+            test = UNTest(
+                dgm=dgm_k,
+                k=k,
+                alpha=alpha,
+                correction_strategy=correction_method,
+                method="universal_null:median",
+                max_threshold=self.max_eps
+            )
+            results["universal_null:median"] = test.results()
+
+        if "universal_null:mean" in methods:
+            test = UNTest(
+                dgm=dgm_k,
+                k=k,
+                alpha=alpha,
+                correction_strategy=correction_method,
+                method="universal_null:mean",
+                max_threshold=self.max_eps
+            )
+            results["universal_null:mean"] = test.results()
+
+        if "bottleneck" in methods or "bottleneck:subsample" in methods:
+            test = BNTest(
+                point_cloud=self.pc,
+                dgm=dgm_k,
+                alpha=alpha,
+                method="bottleneck:subsample",
+                is_distance_matrix=self.is_dist,
+            )
+            results["bottleneck:subsample"] = test.results()
+
+        if "bottleneck:shells" in methods:
+            test = BNTest(point_cloud=self.pc, dgm=dgm_k,
+                          alpha=alpha, method="bottleneck:shells", is_distance_matrix=self.is_dist,)
+            results["bottleneck:shells"] = test.results()
+
+        if "bottleneck:density" in methods:
+            test = BNTest(point_cloud=self.pc, dgm=dgm_k,
+                          alpha=alpha, method="bottleneck:density", is_distance_matrix=self.is_dist,)
+            results["bottleneck:density"] = test.results()
+
+        if "bottleneck:concentration" in methods:
+            test = BNTest(point_cloud=self.pc, dgm=dgm_k,
+                          alpha=alpha, method="bottleneck:concentration", is_distance_matrix=self.is_dist,)
+            results["bottleneck:concentration"] = test.results()
+
+        self._cached_results = results
+        return results
+
+    def display_results(
+        self,
+        results: dict = None,
+        method: str = "all",
+        plot: str = "both",
+    ) -> None:
+        """
+        Visualise hypothesis test results.
+
+        results : dict, optional
+            Output of hypothesis_test.  Uses the most recent cached run
+            when omitted.
+        method : str
+            Which method to plot, or "all" for every method in results.
+        plot : str
+            "diagram", "barcode", or "both".
+        """
+        if results is None:
+            if not self._cached_results:
+                raise ValueError(
+                    "No results to display. Pass a results dict or call "
+                    "hypothesis_test first."
+                )
+            results = self._cached_results
+
+        if not isinstance(results, dict):
+            raise ValueError(
+                "results must be a dict returned by hypothesis_test.")
+
+        if plot not in ("diagram", "barcode", "both"):
+            raise ValueError(
+                f"plot must be 'diagram', 'barcode', or 'both', got {plot!r}."
+            )
+
+        available = list(results.keys())
+        if method == "all":
+            methods_to_plot = available
+        else:
+            if method not in available:
+                raise ValueError(
+                    f"method {method!r} not found in results. Available: {available}."
+                )
+            methods_to_plot = [method]
+
+        n_cols = 2 if plot == "both" else 1
+        n_rows = len(methods_to_plot)
+
+        fig, axes = plt.subplots(
+            n_rows, n_cols,
+            figsize=(6 * n_cols, 5 * n_rows),
+            squeeze=False,
+        )
+        fig.suptitle(f"H_{self.k} persistence results", fontsize=14)
+
+        for row, mname in enumerate(methods_to_plot):
+            res = results[mname]
+            results_array = res["results_array"]
+            thr = res.get("threshold", np.nan)
+
+            births = results_array[:, 0]
+            deaths = results_array[:, 1]
+            pers = deaths - births
+            sig = results_array[:, 4].astype(bool)
+            ax_idx = 0
+
+            if plot in ("diagram", "both"):
+                ax = axes[row, ax_idx]
+                finite_deaths = deaths[np.isfinite(deaths)]
+                lim = finite_deaths.max() * 1.05 if len(finite_deaths) else 1.0
+                xs = np.linspace(0, lim, 300)
+
+                ax.plot([0, lim], [0, lim], "k--", lw=0.8,
+                        alpha=0.4, label="diagonal")
+
+                if not np.isnan(thr):
+                    if np.isinf(thr):
+                        # inf threshold = everything is noise: shade the entire upper triangle
+                        ax.fill_between(xs, xs, lim,
+                                        color="steelblue", alpha=0.07, label="noise band (all)")
+                    elif "universal_null" in mname:
+                        # Threshold is a multiplicative ratio: death = (pi*)(birth)
+                        ax.plot(xs, thr * xs, color="steelblue", lw=1.2,
+                                linestyle="--", alpha=0.7, label=f"pi_min = {thr:.2f}")
+                        ax.fill_between(xs, xs, thr * xs,
+                                        color="steelblue", alpha=0.07, label="noise band")
+                    else:
+                        # Threshold is an additive offset: death = birth + 2c_n
+                        ax.plot(xs, xs + thr, color="steelblue", lw=1.2,
+                                linestyle="--", alpha=0.7, label=f"2c_n = {thr:.3f}")
+                        ax.fill_between(xs, xs, xs + thr,
+                                        color="steelblue", alpha=0.07, label="noise band")
+
+                ax.scatter(births[~sig], deaths[~sig], s=8,  alpha=0.4,
+                           color="steelblue", label="noise")
+                ax.scatter(births[sig],  deaths[sig],  s=9,  alpha=0.9,
+                           color="crimson", label=f"significant ({sig.sum()})", zorder=5)
+
+                ax.set_xlabel("birth")
+                ax.set_ylabel("death")
+                ax.set_title(
+                    f"{mname} — significance persistence diagram ({sig.sum()} significant)")
+                ax.set_aspect("equal")
+                ax.set_xlim(0, lim)
+                ax.set_ylim(0, lim)
+                ax.legend(fontsize=8)
+                ax_idx += 1
+
+            if plot in ("barcode", "both"):
+                ax = axes[row, ax_idx]
+                order = np.argsort(pers)[::-1]
+
+                for rank, idx in enumerate(order):
+                    color = "crimson" if sig[idx] else "steelblue"
+                    alpha_val = 0.9 if sig[idx] else 0.25
+                    lw = 3.5 if sig[idx] else 1.0
+                    ax.hlines(rank, births[idx], deaths[idx],
+                              colors=color, linewidth=lw, alpha=alpha_val)
+
+                ax.set_xlabel("filtration value epsilon")
+                ax.set_ylabel("bar rank")
+                ax.set_title(
+                    f"{mname} — significance barcode ({sig.sum()} significant)")
+                ax.invert_yaxis()
+
+        plt.tight_layout()
+        plt.show()
+
+    def save(self, path: str) -> None:
+        """
+        Save the Phantom instance to disk using pickle.
+        """
+        os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+        with open(path, "wb") as f:
+            pickle.dump(self, f)
+        print(f"Saved Phantom to {path}")
+
+    @classmethod
+    def load(cls, path: str) -> "Phantom":
+        """
+        Load a Phantom instance from disk.
+        """
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"No Phantom file found at {path!r}.")
+        with open(path, "rb") as f:
+            obj = pickle.load(f)
+        if not isinstance(obj, cls):
+            raise TypeError(
+                f"Loaded object is {type(obj).__name__}, expected Phantom."
+            )
+        print(f"Loaded Phantom from {path}")
+        return obj

tdaphantom-1.0.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: tdaphantom
+Version: 1.0.0
+Summary: Statistical hypothesis testing for persistence diagrams and barcodes
+Author: W. Moriarty
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: gudhi>=3.11.0
+Requires-Dist: ripser>=0.6.14
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# TDA-PHANTOM
+Topological data analysis -
+Persistent Homology Analysis via Null Testing On Manifolds (TDA-PHANTOM)
+is a tool for statistically analysing significance of persistence diagrams and barcodes.
+
+This project implements hypothesis tests from:
+
+- *Confidence Sets for Persistence Diagrams*
+  Fasy et al. (2014)
+  DOI: https://doi.org/10.1214/14-AOS1252
+
+- *A Universal Null-Distribution for Topological Data Analysis*
+  Bobrowski and Skraba (2023)
+  DOI: https://doi.org/10.1038/s41598-023-37842-2
+
+
+## Installation
+
+Via [PyPI](https://pypi.org/project/tdaphantom/):
+
+```bash
+pip install tdaphantom
+```
+Or you can clone this repository and install it manually:
+
+```bash
+python setup.py install
+```
+
+## Overview
+
+This tool can build a Vietoris-Rips complex from either a point cloud or distance matrix.
+
+It can then be used to visualise the persistence diagram for that complex, and run various hypothesis tests for it.
+
+The results of these hypothesis tests can be analysed via a return results array, or visualised in a signifiance persistence diagram.
+
+## Example Usage
+
+### Generate data
+
+```python
+def _make_circle(n=2000, noise=0.03, seed=1):
+    rng   = np.random.default_rng(seed)
+    theta = rng.uniform(0, 2 * np.pi, n)
+    pts   = np.stack([np.cos(theta), np.sin(theta)], axis=1)
+    return pts + rng.normal(0, noise, pts.shape)
+
+pc_circle = _make_circle()
+```
+
+### Init Phantom class
+
+```python
+phantom_circle = Phantom(pc_circle)
+```
+### Calculate persistence diagram
+Here we go up to homological dimension 1
+
+```python
+phantom_circle.calculate_dgms_from_point_cloud_ripser(k=1)
+```
+
+
+### Display persistence diagram
+
+```python
+phantom_circle.display_dgms()
+```
+
+![Persistence diagram for a circle using phatom](./README_SRC/circle_dgms.png)
+
+### Run hypothesis test
+```python
+alpha      = 0.01
+correction = None
+methods    = ["universal_null"]
+
+phantom_circle.hypothesis_test(alpha, correction_method=correction, methods=methods, k=1)
+```
+
+### Display signifiance persistence diagram
+
+```python
+phantom_circle.display_results()
+```
+![signifiance Persistence diagram for a circle using phatom](./README_SRC/circle_sig.png)
+
+
+## Basic useage
+
+
+## Avaliable methods
+
+## Universal null median
+### Useage
+### Theory
+
+## Universal null mean
+### Useage
+### Theory
+
+## Bottleneck subsampling
+### Useage
+### Theory
+
+## TODO
+
+* Add bottleneck shells
+* Add bottleneck density
+* Add bottleneck concentration
+* Add more integeration tests
+* Add more unit tests

tdaphantom-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+tdaphantom/__init__.py,sha256=iJDuo6aPdl6Qem3GwpjEdn9EX_XKjPwY781CetJLSjI,33
+tdaphantom/tdaphantom.py,sha256=eFKmHGkwMiGN9RCPYglmiO-oksrvGME4HJXVfg4TXos,22860
+tdaphantom/hypothesis_tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tdaphantom/hypothesis_tests/bottleneck_distance_tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tdaphantom/hypothesis_tests/bottleneck_distance_tests/bottleneck_distance_test.py,sha256=a8PWjB5GxtqpmOaXI9jNsleBJe0Cib088INF4hAaszI,5789
+tdaphantom/hypothesis_tests/universal_null_tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tdaphantom/hypothesis_tests/universal_null_tests/universal_null_hypothesis_test.py,sha256=ii-tTrhOUr93NWhciy825KnFB0DMnQg3l7VMKAgIuCM,8427
+tdaphantom/metrics/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tdaphantom/metrics/metrics.py,sha256=YqnB2lEVnw0XR-0Lf0KOtIFydRsvzHGZAyaLq2865Do,2112
+tdaphantom-1.0.0.dist-info/licenses/LICENSE,sha256=Ard-MXyIkSN7P8HKKqWGjY0pe9DVSWds26caXlVraI8,1065
+tdaphantom-1.0.0.dist-info/METADATA,sha256=eRDFEFGSmmDXdZupp_lBlDXMILTk72RDSc5UYLaVlNc,3238
+tdaphantom-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tdaphantom-1.0.0.dist-info/top_level.txt,sha256=e3T5mrvKbsHzwq_0yhGFQUQXt5Gn1adeLHjG0ZcqzxQ,11
+tdaphantom-1.0.0.dist-info/RECORD,,

tdaphantom-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tdaphantom-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moriarty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tdaphantom-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tdaphantom