ggml-ot 0.9.1__tar.gz

ggml_ot-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Damin Kühn
+
+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.

ggml_ot-0.9.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.3
+Name: ggml-ot
+Version: 0.9.1
+Summary: Global Ground Metric Learning
+Author: Damin Kuehn
+Author-email: kuehn@cs.rwth-aachen.de
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Sphinx
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Dist: anndata (>=0.11.4,<0.12.0)
+Requires-Dist: matplotlib (>=3.10.1,<4.0.0)
+Requires-Dist: numpy (>=2.2.4,<3.0.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: pot (>=0.9.5,<0.10.0)
+Requires-Dist: pydiffmap (>=0.2.0.1,<0.3.0.0)
+Requires-Dist: scanpy (>=1.11.1,<2.0.0)
+Requires-Dist: scikit-learn (>=1.1,<1.6)
+Requires-Dist: scipy (>=1.15.2,<2.0.0)
+Requires-Dist: seaborn (>=0.13.2,<0.14.0)
+Requires-Dist: torch (>=2.6.0,<3.0.0)
+Requires-Dist: tqdm (>=4.67.1,<5.0.0)
+Requires-Dist: umap-learn (>=0.5.7,<0.6.0)
+Project-URL: Homepage, https://github.com/DaminK/ggml-ot
+Project-URL: Issues, https://github.com/DaminK/ggml-ot/issues
+Description-Content-Type: text/markdown
+
+# GGML-OT
+
+<img src="https://github.com/user-attachments/assets/5c522e9b-8eb3-4b0a-8ae5-bb8671eba3d6" width="300" />
+
+## Abstract
+
+Optimal transport (OT) provides a robust framework for comparing probability distributions.
+Its effectiveness is significantly influenced by the choice of the underlying ground metric.
+Traditionally, the ground metric has either been (i) predefined, e.g. as a Euclidean metric, or (ii) learned in a supervised way, by utilizing labeled data to learn a suitable ground metric for enhanced task-specific performance.
+While predefined metrics often do not account for the inherent structure and varying significance of different features in the data, existing supervised ground metric learning methods often fail to generalize across multiple classes or are limited to distributions with shared supports.
+To address this issue, this paper introduces a novel approach for learning metrics for arbitrary distributions over a shared metric space.
+Our method differentiates elements like a global metric, but requires only class labels on a distribution-level for training akin a ground metric.
+The resulting learned global ground metric enables more accurate OT distances, which can significantly improve clustering and classification tasks. It can create task-specific shared embeddings across elements of different distributions including unseen data.
+
+## Installation
+
+### Via pip
+
+```terminal
+pip install ggml-ot
+```
+
+### Manual
+
+```terminal
+git clone https://github.com/DaminK/ggml-ot
+cd ggml-ot
+pip install poetry
+poetry lock && poetry install
+```
+
+### Development installation
+
+```terminal
+git clone https://github.com/DaminK/ggml-ot
+cd ggml-ot
+pip install poetry
+peotry lock && poetry install --with dev
+pre-commit install
+```
+
+## Citation
+
+If you use this code in your research, please cite the following paper:
+> Global Ground Metric Learning with Applications to scRNA data
+>
+> Damin Kuehn and Michael T. Schaub, Department of Computer Science RWTH Aachen
+>
+> Published at AISTATS2025 (DOI will follow)
+

ggml_ot-0.9.1/README.md

@@ -0,0 +1,49 @@
+# GGML-OT
+
+<img src="https://github.com/user-attachments/assets/5c522e9b-8eb3-4b0a-8ae5-bb8671eba3d6" width="300" />
+
+## Abstract
+
+Optimal transport (OT) provides a robust framework for comparing probability distributions.
+Its effectiveness is significantly influenced by the choice of the underlying ground metric.
+Traditionally, the ground metric has either been (i) predefined, e.g. as a Euclidean metric, or (ii) learned in a supervised way, by utilizing labeled data to learn a suitable ground metric for enhanced task-specific performance.
+While predefined metrics often do not account for the inherent structure and varying significance of different features in the data, existing supervised ground metric learning methods often fail to generalize across multiple classes or are limited to distributions with shared supports.
+To address this issue, this paper introduces a novel approach for learning metrics for arbitrary distributions over a shared metric space.
+Our method differentiates elements like a global metric, but requires only class labels on a distribution-level for training akin a ground metric.
+The resulting learned global ground metric enables more accurate OT distances, which can significantly improve clustering and classification tasks. It can create task-specific shared embeddings across elements of different distributions including unseen data.
+
+## Installation
+
+### Via pip
+
+```terminal
+pip install ggml-ot
+```
+
+### Manual
+
+```terminal
+git clone https://github.com/DaminK/ggml-ot
+cd ggml-ot
+pip install poetry
+poetry lock && poetry install
+```
+
+### Development installation
+
+```terminal
+git clone https://github.com/DaminK/ggml-ot
+cd ggml-ot
+pip install poetry
+peotry lock && poetry install --with dev
+pre-commit install
+```
+
+## Citation
+
+If you use this code in your research, please cite the following paper:
+> Global Ground Metric Learning with Applications to scRNA data
+>
+> Damin Kuehn and Michael T. Schaub, Department of Computer Science RWTH Aachen
+>
+> Published at AISTATS2025 (DOI will follow)

ggml_ot-0.9.1/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "ggml-ot"
+authors = [{ name = "Damin Kuehn", email = "kuehn@cs.rwth-aachen.de" }]
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Development Status :: 5 - Production/Stable",
+  "Framework :: Sphinx",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Healthcare Industry",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+  "tqdm (>=4.67.1,<5.0.0)",
+  "scipy (>=1.15.2,<2.0.0)",
+  "matplotlib (>=3.10.1,<4.0.0)",
+  "seaborn (>=0.13.2,<0.14.0)",
+  "umap-learn (>=0.5.7,<0.6.0)",
+  "numpy (>=2.2.4,<3.0.0)",
+  "pandas (>=2.2.3,<3.0.0)",
+  "pot (>=0.9.5,<0.10.0)",
+  "pydiffmap (>=0.2.0.1,<0.3.0.0)",
+  "anndata (>=0.11.4,<0.12.0)",
+  "torch (>=2.6.0,<3.0.0)",
+  "scanpy (>=1.11.1,<2.0.0)",
+  "scikit-learn (>=1.1,<1.6)",
+]
+[project.urls]
+Homepage = "https://github.com/DaminK/ggml-ot"
+Issues = "https://github.com/DaminK/ggml-ot/issues"
+
+[tool.poetry]
+name = "ggml-ot"
+version = "0.9.1"
+description = "Global Ground Metric Learning"
+authors = ["Damin Kuehn <damin.kuehn@rwth-aachen.de>"]
+
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = "^3.2.1"
+ipykernel = "^6.29.5"
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+sphinx = "^8.2.3"
+sphinx-autorun = "^2.0.0"
+sphinx-rtd-theme = "^3.0.2"
+myst-parser = "^4.0.1"
+
+[tool.poetry.group.test]
+optional = true
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.3.5"
+pytest-cov = "^6.1.1"
+ruff = "^0.11.6"
+
+[tool.ruff]
+select = ["E4", "E7", "E9", "F"]
+task-tags = ["TODO", "FIXME"]
+output-format = "github"
+respect-gitignore = true
+
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-format = true
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+

ggml_ot-0.9.1/src/ggml_ot/__init__.py

@@ -0,0 +1,9 @@
+from .data import scRNA_Dataset, synthetic_Dataset
+from .plot import (
+    plot_emb,
+    plot_heatmap,
+    plot_clustermap,
+    plot_distribution,
+    plot_ellipses,
+)
+from .ggml import ggml

ggml_ot-0.9.1/src/ggml_ot/benchmark/__init__.py

@@ -0,0 +1,2 @@
+from .knn import *
+from .pivoted_chol import *

ggml_ot-0.9.1/src/ggml_ot/benchmark/knn.py

@@ -0,0 +1,258 @@
+from sklearn.metrics import confusion_matrix
+from sklearn.model_selection import StratifiedShuffleSplit, GroupShuffleSplit
+from sklearn.neighbors import KNeighborsClassifier
+from sklearn.metrics import silhouette_score
+from sklearn.metrics.cluster import adjusted_rand_score
+
+import numpy as np
+import seaborn as sns
+import numpy.typing as npt
+import matplotlib.pyplot as plt
+from IPython.display import display
+import warnings
+
+
+def ShuffleSplit(
+    labels,
+    n_splits=10,
+    train_size=0.4,
+    test_size=0.4,
+    validation_size=0.2,
+    distribution_labels=None,
+):
+    if validation_size > 0:
+        # draw validation inds in test split and later split into two test sets
+        test_size = test_size + validation_size
+    if n_splits > 0:
+        if distribution_labels is None:
+            sss = StratifiedShuffleSplit(
+                n_splits=n_splits,
+                test_size=test_size,
+                train_size=train_size,
+                random_state=0,
+            )
+            train_test_inds = sss.split(np.zeros(len(labels)), labels)
+        else:
+            # split patients into test and train,should be stratified
+            # distribution_labels
+
+            # unique_distribution_labels = np.unique(distribution_labels)
+            # distribution_train_test_inds = sss.split(np.zeros(len(unique_distribution_labels)), unique_distribution_labels)
+
+            gss = GroupShuffleSplit(
+                n_splits=n_splits,
+                test_size=test_size,
+                train_size=train_size,
+                random_state=0,
+            )
+            print('shapes')
+            print(np.zeros(len(labels)).shape)
+            print(labels.shape)
+            print(distribution_labels.shape)
+            train_test_inds = gss.split(
+                np.zeros(len(labels)), labels, distribution_labels
+            )
+
+            # train_test_inds = []
+            # for i, (train_distribution_index, test_distribution_index) in enumerate(distribution_train_test_inds):
+            #    train_label_ind = [distribution_labels == unique_distribution_labels[train_distribution_index]]
+            #    test_label_ind = [distribution_labels == unique_distribution_labels[test_distribution_index]]
+            #    #for each patient split, do test and train splits between cells from both splits
+            #    train = sss.split(np.zeros(len(labels)), labels)
+            #    test =
+    else:
+        # Train = Test
+        train_test_inds = [(np.arange(len(labels)), np.arange(len(labels)))]
+
+    if validation_size > 0:
+        test_size = test_size - validation_size
+
+    return train_test_inds
+
+
+def knn_from_dists(
+    dists,
+    labels,
+    n_splits=20,
+    distribution_labels=None,
+    n_neighbors=5,
+    weights=None,
+    test_size=0.2,
+    train_size=None,
+):
+    predicted_labels, true_labels, test_indices, scores = [], [], [], []
+
+    train_test_inds = ShuffleSplit(
+        labels,
+        n_splits,
+        train_size,
+        test_size,
+        validation_size=0,
+        distribution_labels=distribution_labels,
+    )
+    # , np.arange(len(labels)))
+
+    for i, (train_index, test_index) in enumerate(train_test_inds):
+        print(train_index)
+        print(test_index)
+        train_dists = dists[np.ix_(train_index, train_index)]
+        test_to_train_dists = dists[np.ix_(test_index, train_index)]
+
+        neigh = KNeighborsClassifier(
+            n_neighbors=n_neighbors, metric='precomputed', weights=weights
+        )
+        neigh.fit(train_dists, [labels[t] for t in train_index])
+
+        predicted_labels.append(neigh.predict(test_to_train_dists))
+        true_labels.append(np.asarray([labels[t] for t in test_index]))
+        scores.append(neigh.score(test_to_train_dists, true_labels[-1]))
+        test_indices.append(test_index)
+        # ari.append(adjusted_rand_score(predicted_labels[-1],true_labels[-1]))
+
+    ari = adjusted_rand_score(
+        np.concatenate(true_labels), np.concatenate(predicted_labels)
+    )
+
+    return predicted_labels, true_labels, scores, ari, test_indices
+
+
+def silhouette_score_wrapper(dists, labels):
+    # wrapper function as fill diagonal is only available as inplace operation. It is needed to catch cases where due to numerical errors the distance of a graph to itself may be very close to zero, but not zero which is required by sklearn silhoute score method
+    zero_dia_dists = np.copy(dists)
+    np.fill_diagonal(zero_dia_dists, 0)
+    return silhouette_score(zero_dia_dists, labels, metric='precomputed')
+
+
+def compute_dists(Graphs, Graphs2=None, method='TiedOT'):
+    dist, plan = methods[method](Graphs, Graphs2)
+    dist[dist < 0] = 0
+    return dist
+
+
+def get_dist_precomputed(precomputed_dists, ind1, ind2):
+    return precomputed_dists[ind1, :][:, ind2]
+
+
+def plot_1split(predicted, true, title=None, ax=None):
+    annot_labels_ind = np.unique(true, return_index=True)[1]
+    annot_labels = true[annot_labels_ind]
+    # ind
+    cf_matrix = confusion_matrix(true, predicted, labels=annot_labels)
+    if ax is None:
+        plt.figure()
+    ax = sns.heatmap(
+        cf_matrix,
+        annot=True,  # fmt='.0',
+        cmap='Blues',
+        xticklabels=annot_labels,
+        yticklabels=annot_labels,
+        ax=ax,
+        fmt='g',
+    )
+    ax.set(xlabel='Predicted Label', ylabel='True Label')
+    ax.set_title(title)
+
+
+def plot_table(df, tranpose=False):
+    format_df = df
+    format_df.set_index('method', inplace=True)
+    if tranpose:
+        format_df = format_df.transpose()
+    display(format_df)
+    print(
+        format_df.to_latex(
+            index=True,
+            # formatters={"name": str.upper},
+            float_format='{:.2f}'.format,
+        )
+    )
+
+
+def VI(
+    labels1: npt.NDArray[np.int32],
+    labels2: npt.NDArray[np.int32],
+    torch: bool = True,
+    device: str = 'cpu',
+    return_split_merge: bool = False,
+):
+    """
+    Calculates the Variation of Information between two clusterings.
+
+    Arguments:
+    labels1: flat int32 array of labels for the first clustering
+    labels2: flat int32 array of labels for the second clustering
+    torch: whether to use torch, default:True
+    device: device to use for torch, default:"cpu"
+    return_split_merge: whether to return split and merge terms, default:False
+
+    Returns:
+    vi: variation of information
+    vi_split: split term of variation of information
+    vi_merge: merge term of variation of information
+    splitters(optional): labels of labels2 which are split by labels1. splitters[i,0] is the contribution of the i-th splitter to the VI and splitters[i,1] is the corresponding label of the splitter
+    mergers(optional): labels of labels1 which are merging labels from labels2. mergers[i,0] is the contribution of the i-th merger to the VI and mergers[i,1] is the corresponding label of the merger
+    """
+    if labels1.ndim > 1 or labels2.ndim > 1:
+        warnings.warn(
+            f"Inputs of shape {labels1.shape}, {labels2.shape} are not one-dimensional -- inputs will be flattened."
+        )
+        labels1 = labels1.flatten()
+        labels2 = labels2.flatten()
+
+    if torch:
+        return VI_torch(
+            labels1, labels2, device=device, return_split_merge=return_split_merge
+        )
+    else:
+        return VI_np(labels1, labels2, return_split_merge=return_split_merge)
+
+
+def VI_np(labels1, labels2, return_split_merge=False):
+    assert len(labels2) == len(labels1)
+    size = len(labels2)
+
+    mutual_labels = (labels1.astype(np.uint64) << 32) + labels2.astype(np.uint64)
+
+    sm_unique, sm_inverse, sm_counts = np.unique(
+        labels2, return_inverse=True, return_counts=True
+    )
+    fm_unique, fm_inverse, fm_counts = np.unique(
+        labels1, return_inverse=True, return_counts=True
+    )
+    _, mutual_inverse, mutual_counts = np.unique(
+        mutual_labels, return_inverse=True, return_counts=True
+    )
+
+    terms_mutual = -np.log(mutual_counts / size) * mutual_counts / size
+    terms_mutual_per_count = (
+        terms_mutual[mutual_inverse] / mutual_counts[mutual_inverse]
+    )
+    terms_sm = -np.log(sm_counts / size) * sm_counts / size
+    terms_fm = -np.log(fm_counts / size) * fm_counts / size
+    if not return_split_merge:
+        terms_mutual_sum = np.sum(terms_mutual_per_count)
+        vi_split = terms_mutual_sum - terms_sm.sum()
+        vi_merge = terms_mutual_sum - terms_fm.sum()
+        vi = vi_split + vi_merge
+        return vi, vi_split, vi_merge
+
+    vi_split_each = np.zeros(len(sm_unique))
+    np.add.at(vi_split_each, sm_inverse, terms_mutual_per_count)
+    vi_split_each -= terms_sm
+    vi_merge_each = np.zeros(len(fm_unique))
+    np.add.at(vi_merge_each, fm_inverse, terms_mutual_per_count)
+    vi_merge_each -= terms_fm
+
+    vi_split = np.sum(vi_split_each)
+    vi_merge = np.sum(vi_merge_each)
+    vi = vi_split + vi_merge
+
+    i_splitters = np.argsort(vi_split_each)[::-1]
+    i_mergers = np.argsort(vi_merge_each)[::-1]
+
+    vi_split_sorted = vi_split_each[i_splitters]
+    vi_merge_sorted = vi_merge_each[i_mergers]
+
+    splitters = np.stack([vi_split_sorted, sm_unique[i_splitters]], axis=1)
+    mergers = np.stack([vi_merge_sorted, fm_unique[i_mergers]], axis=1)
+    return vi, vi_split, vi_merge, splitters, mergers

ggml_ot-0.9.1/src/ggml_ot/benchmark/pivoted_chol.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#  pivoted_chol.py Author "Nathan Wycoff <nathanbrwycoff@gmail.com>" Date 01.14.2020
+
+## A pivoted cholesky function for kernel functions
+import numpy as np
+
+
+def pivoted_chol(get_diag, get_row, M, err_tol=1e-6):
+    """
+    A simple python function which computes the Pivoted Cholesky decomposition/approximation of positive semi-definite operator. Only diagonal elements and select rows of that operator's matrix represenation are required.
+
+    get_diag - A function which takes no arguments and returns the diagonal of the matrix when called.
+    get_row - A function which takes 1 integer argument and returns the desired row (zero indexed).
+    M - The maximum rank of the approximate decomposition; an integer.
+    err_tol - The maximum error tolerance, that is difference between the approximate decomposition and true matrix, allowed. Note that this is in the Trace norm, not the spectral or frobenius norm.
+
+    Returns: R, an upper triangular matrix of column dimension equal to the target matrix. It's row dimension will be at most M, but may be less if the termination condition was acceptably low error rather than max iters reached.
+    """
+
+    d = np.copy(get_diag())
+    N = len(d)
+
+    pi = list(range(N))
+
+    R = np.zeros([M, N])
+
+    err = np.sum(np.abs(d))
+
+    m = 0
+    while (m < M) and (err > err_tol):
+        i = m + np.argmax([d[pi[j]] for j in range(m, N)])
+
+        tmp = pi[m]
+        pi[m] = pi[i]
+        pi[i] = tmp
+
+        R[m, pi[m]] = np.sqrt(d[pi[m]])
+        Apim = get_row(pi[m])
+        for i in range(m + 1, N):
+            if m > 0:
+                ip = np.inner(R[:m, pi[m]], R[:m, pi[i]])
+            else:
+                ip = 0
+            R[m, pi[i]] = (Apim[pi[i]] - ip) / R[m, pi[m]]
+            d[pi[i]] -= pow(R[m, pi[i]], 2)
+
+        err = np.sum([d[pi[i]] for i in range(m + 1, N)])
+        m += 1
+
+    R = R[:m, :]
+
+    return R
+
+
+# Example:
+N = 10
+S = np.random.normal(size=[N, N])
+A = np.matmul(S.T, S)
+
+# Important to copy as diag may not be writable depending on np version
+get_diag = lambda: np.diag(A).copy()
+get_row = lambda i: A[i, :]
+R = pivoted_chol(get_diag, get_row, M=N)
+
+# R.T @ R is numerically equal to A.
+print(np.linalg.norm(np.matmul(R.T, R) - A))

ggml_ot-0.9.1/src/ggml_ot/data/__init__.py

@@ -0,0 +1,3 @@
+from .scRNA import *  # noqa
+from .synth import *  # noqa
+from .util import *  # noqa