flowgem 0.1.0__py3-none-any.whl

flowgem/__init__.py

@@ -0,0 +1,18 @@
+# read version from installed package
+from importlib.metadata import version
+
+__version__ = version("flowgem")
+
+# public API
+from flowgem.api import FlowGEM
+from flowgem.core import sample_flowgem
+from flowgem.optim import opt_wb
+from flowgem.bandwidth import sigma_heuristic_pairs, evaluate_sigma
+
+__all__ = [
+    "FlowGEM",
+    "sample_flowgem",
+    "opt_wb",
+    "sigma_heuristic_pairs",
+    "evaluate_sigma",
+]

flowgem/api.py

@@ -0,0 +1,253 @@
+"""Public, class-based API for FLOWGEM.
+
+Wraps the core sampler in a scikit-learn-style fit/generate interface. The
+user gives one incomplete array with NaN as missing entries. The
+observation mask is built in fit(), and a fresh initial ensemble is built on
+each generate() call.
+"""
+
+import numpy as np
+import torch
+
+from flowgem.core import sample_flowgem
+
+
+class FlowGEM:
+    """Generative sampler for missing at random (MAR) data via an approximate
+    Wasserstein gradient flow.
+
+    The user passes one incomplete array with NaN marking the missing entries.
+    The observation mask and the initial particle ensemble are built
+    internally. The interface follows the scikit-learn fit/generate pattern.
+
+    Each generate() call draws a fresh initial ensemble, so repeated calls
+    return different samples. With a fixed random_state the sequence of calls
+    is reproducible.
+
+    Parameters
+    ----------
+    T : int, default=1000
+        Number of gradient-flow (time) steps.
+    eta : float, default=0.01
+        Step size of the forward-Euler update.
+    sigma : float, list of float, or None, default=None
+        Kernel bandwidth. If None, a median heuristic picks it. A float fixes
+        the bandwidth. A list is cross-validated over the candidates.
+    init : {"mice", "sample"} or array-like, default="mice"
+        How the initial particles are built. "mice" imputes with the
+        hyperimpute MICE implementation. "sample" resamples observed values
+        column by column. An array is used directly as the initialisation.
+    grad_tol : float, default=0.01
+        Early-stopping tolerance on the relative gradient norm.
+    min_iter : int, default=10
+        Minimum number of steps before early stopping may trigger.
+    dtype : torch.dtype, default=torch.float64
+        Numerical precision used throughout.
+    random_state : int or None, default=None
+        Seed for the sequence of generate() calls, for reproducibility.
+
+    Attributes
+    ----------
+    mask_ : torch.Tensor
+        Observation mask built in fit(). A 1 marks an observed entry.
+    X_obs_ : torch.Tensor
+        Observed data with missing entries filled by zero.
+    X_incomplete_ : torch.Tensor
+        The incomplete data kept from fit(), used to build a fresh initial
+        ensemble on each generate() call.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from flowgem import FlowGEM
+    >>> X = np.random.default_rng(0).standard_normal((100, 3))
+    >>> X[0, 1] = np.nan                  # mark a missing value
+    >>> model = FlowGEM(T=1000, random_state=0)
+    >>> X_complete = model.fit(X).generate()
+    """
+
+    def __init__(self, T=1000, eta=0.01, sigma=None, init="mice",
+                 grad_tol=0.01, min_iter=10, dtype=torch.float64,
+                 random_state=None):
+        self.T = T
+        self.eta = eta
+        self.sigma = sigma
+        self.init = init
+        self.grad_tol = grad_tol
+        self.min_iter = min_iter
+        self.dtype = dtype
+        self.random_state = random_state
+
+    def fit(self, X_incomplete):
+        """Prepare the sampler from an incomplete dataset.
+
+        Parameters
+        ----------
+        X_incomplete : array-like of shape (n_samples, d_features)
+            Input data with missing entries marked as NaN.
+
+        Returns
+        -------
+        self : FlowGEM
+            The fitted instance, so fit(...).generate() can be chained.
+
+        Raises
+        ------
+        ValueError
+            If the input is not 2D, has no NaN (nothing marked missing), or
+            has infinite values.
+        """
+        # accept numpy arrays, lists, or tensors, in the chosen dtype
+        X = torch.as_tensor(X_incomplete, dtype=self.dtype)
+
+        if X.ndim != 2:
+            raise ValueError(
+                f"X_incomplete must be 2D (n_samples, n_features), got {X.ndim}D"
+            )
+        if not torch.isnan(X).any():
+            raise ValueError(
+                "X_incomplete has no NaN values; nothing is marked as missing. "
+                "Mark missing entries with NaN."
+            )
+        if torch.isinf(X).any():
+            raise ValueError(
+                "X_incomplete contains infinite values; only finite values "
+                "and NaN (for missing entries) are supported."
+            )
+
+        # observation mask: 1 = observed, 0 = missing (matches the core code)
+        self.mask_ = (~torch.isnan(X)).to(self.dtype)
+
+        # observed data, NaN filled with 0 as a placeholder
+        # (the sampler reads only the observed entries, through the mask)
+        self.X_obs_ = torch.nan_to_num(X, nan=0.0)
+
+        # keep the incomplete data: the initial ensemble is rebuilt on each
+        # generate() call, so repeated calls give different samples
+        self.X_incomplete_ = X
+
+        # persistent RNG for the sequence of generate() calls. With a fixed
+        # random_state the calls differ but the whole sequence is reproducible.
+        self._rng = np.random.default_rng(self.random_state)
+
+        return self
+
+    def _build_X0(self, X, seed):
+        """Build an initial particle ensemble from the incomplete data.
+
+        X is the incomplete tensor (with NaN). seed makes the construction
+        reproducible. Returns a complete X0 tensor.
+        """
+        init = self.init
+
+        # case 1: user supplied their own initialisation array (deterministic)
+        if not isinstance(init, str):
+            X0 = torch.as_tensor(init, dtype=self.dtype)
+            if X0.shape != X.shape:
+                raise ValueError(
+                    f"Supplied init array has shape {tuple(X0.shape)}, "
+                    f"expected {tuple(X.shape)}"
+                )
+            return X0
+
+        # case 2: MICE (default), via the hyperimpute package
+        if init == "mice":
+            from hyperimpute.plugins.imputers import Imputers
+
+            imputer = Imputers().get("mice", random_state=seed)
+            X0_np = imputer.fit_transform(X.cpu().numpy())
+            X0_np = np.asarray(X0_np, dtype=float).copy()
+            return torch.as_tensor(X0_np, dtype=self.dtype)
+
+        # case 3: resample observed values column by column (the paper's simulation init)
+        if init == "sample":
+            g = torch.Generator().manual_seed(seed)
+
+            X0 = X.clone()
+            _, d = X.shape
+            for j in range(d):
+                col = X[:, j]
+                missing = torch.isnan(col)
+                observed = col[~missing]
+                n_missing = int(missing.sum())
+                if n_missing > 0:
+                    if observed.numel() == 0:
+                        raise ValueError(f"Column {j} has no observed values to sample from")
+                    idx = torch.randint(0, observed.numel(), (n_missing,), generator=g)
+                    X0[missing, j] = observed[idx]
+            return X0
+
+        raise ValueError(
+            f"Unknown init {init!r}; use 'mice', 'sample', or supply an array"
+        )
+
+    def generate(self, return_trajectory=False):
+        """Generate a complete sample of the same size as the fitted data.
+
+        Each call builds a new initial ensemble Repeated calls on the
+        same model return different samples. With a fixed random_state the
+        sequence of calls is reproducible.
+
+        Parameters
+        ----------
+        return_trajectory : bool
+            If False (default), return only the final sample, of shape (n, d).
+            If True, return the full list of per step snapshots.
+
+        Returns
+        -------
+        numpy.ndarray or list of numpy.ndarray
+            The final sample of shape (n, d), or the full trajectory if
+            return_trajectory is True.
+
+        Raises
+        ------
+        RuntimeError
+            If called before fit().
+
+        Notes
+        -----
+        With init="mice" each call re runs MICE, which can be slow.
+        """
+        if not hasattr(self, "X_incomplete_"):
+            raise RuntimeError("Call fit(...) before generate().")
+
+        # fresh per-call seed drawn from the persistent RNG
+        call_seed = int(self._rng.integers(0, 2**31 - 1))
+
+        # sigma handling: None -> heuristic (sigma_fix=None, sigma_vals=None)
+        #                 float -> fixed
+        #                 list -> cross-validation over candidates
+        sigma_fix = None
+        sigma_vals = None
+        if isinstance(self.sigma, (int, float)):
+            sigma_fix = float(self.sigma)
+        elif self.sigma is not None:
+            sigma_vals = self.sigma
+
+        # build a fresh initial ensemble for this call, and seed torch so the
+        # bandwidth heuristic is reproducible. Save and restore the global RNG
+        # state so the user's other torch code is not disturbed.
+        rng_state = torch.random.get_rng_state()
+        try:
+            torch.manual_seed(call_seed)
+            X0 = self._build_X0(self.X_incomplete_, call_seed)
+            Xhats = sample_flowgem(
+                X0,
+                self.X_obs_,
+                self.mask_,
+                T=self.T,
+                eta=self.eta,
+                grad_tol=self.grad_tol,
+                min_iter=self.min_iter,
+                sigma_fix=sigma_fix,
+                sigma_vals=sigma_vals,
+                dtype=self.dtype,
+            )
+        finally:
+            torch.random.set_rng_state(rng_state)
+
+        # return the full trajectory or just the final snapshot (as numpy arrays)
+        if return_trajectory:
+            return [np.asarray(x) for x in Xhats]
+        return np.asarray(Xhats[-1])

flowgem/bandwidth.py

@@ -0,0 +1,48 @@
+"""Bandwidth (sigma) selection utilities for FLOWGEM.
+
+Everything related to choosing the RBF kernel bandwidth sigma can be found here.
+It includes computing pairwise distances, median heuristic for a quick data-adaptive
+estimate, and CV (cross validation) scoring of candidate sigma.
+These functions are internally used by :class:`flowgem.FlowGEM`. you do not need to call them directly.
+"""
+
+import torch
+
+from flowgem.optim import opt_wb
+
+
+def comp_pairwise_dist(x, y):
+    # in case x and y are not vectors
+    x = x.view(x.shape[0], -1)
+    y = y.view(y.shape[0], -1)
+
+    t1 = torch.tile(torch.sum(x**2, dim=1, keepdim=True), (1, y.shape[0]))
+    t2 = -2 * torch.matmul(x, y.T)
+    t3 = torch.tile(torch.sum(y**2, dim=1, keepdim=True).T, (x.shape[0], 1))
+
+    return t1 + t2 + t3
+
+
+def sigma_heuristic_pairs(X, num_pairs=1000000):
+    n = X.shape[0]
+
+    i = torch.randint(0, n, (num_pairs,))
+    j = torch.randint(0, n, (num_pairs,))
+
+    dvals = torch.norm(X[i] - X[j], dim=1)
+
+    return (0.5 * dvals.median()).sqrt().item()
+
+
+def evaluate_sigma(xpi, xrho, sigma, splits_pi, splits_rho):
+    # See thesis: intentional discrepancy with paper's Remark 1; preserved as-is.
+    psicon = lambda d: 0.5*d*d + d
+
+    obj = 0
+
+    for (train_pi, val_pi), (train_rho, val_rho) in zip(splits_pi, splits_rho):
+        w, b = opt_wb(xpi[train_pi, :], xrho[train_rho, :], torch.cat([xpi[val_pi, :], xrho[val_rho, :]], dim=0), sigma)
+        obj += torch.mean((w[:len(val_pi), :] * xpi[val_pi, :]).sum(dim=1) + b[:len(val_pi)].T).item()
+        obj -= torch.mean(psicon((w[len(val_pi):, :] * xrho[val_rho, :]).sum(dim=1) + b[len(val_pi):].T)).item()
+
+    return obj

flowgem/core.py

@@ -0,0 +1,140 @@
+"""Core FLOWGEM sampler: the discretised Wasserstein gradient flow.
+
+This module performs the whole method. Extracting missingness patterns,
+selecting bandwidths, and evolving the particle ensemble over time as well as using the
+solver from `optim` and the bandwidth utilities from `bandwidth`.
+"""
+
+import logging
+import os
+
+import numpy as np
+import torch
+from joblib import Parallel, delayed
+from sklearn.model_selection import KFold
+from tqdm.auto import tqdm
+
+from flowgem.optim import opt_wb
+from flowgem.bandwidth import sigma_heuristic_pairs, evaluate_sigma
+
+logger = logging.getLogger(__name__)
+
+def sample_flowgem(X0, X_obs, M, T=1000, eta=0.01, grad_tol=0.01, min_iter=10, sigma_fix=None, sigma_vals=None, cv_every=10, dtype=torch.float64):
+    """Evolve a particle cloud along the approximate Wasserstein gradient flow.
+
+    This is the core sampler. It first extracts the distinct missingness patterns.
+    Then it selects the kernel bandwidth, and iteratively updates the particles using
+    local linear velocity estimate on each pattern. It does so until the final
+    time ``T`` or early stopping is reached.
+
+    Parameters
+    ----------
+    X0 : torch.Tensor of shape (n, d)
+        Initial particle ensemble/cloud (a complete array, no NaN).
+    X_obs : torch.Tensor of shape (n, d)
+        Observed data, with missing entries filled by zero.
+    M : torch.Tensor of shape (n, d)
+        Observation mask, 1 marks an observed entry, 0 as a missing one.
+    T : int, default=1000
+        Maximum number of gradient flow steps.
+    eta : float, default=0.01
+        Step size of the forward Euler update.
+    grad_tol : float, default=0.01
+        Early stopping tolerance on the relative gradient norm.
+    min_iter : int, default=10
+        Minimum number of steps before early stopping may trigger.
+    sigma_fix : float or None, default=None
+        Fixed kernel bandwidth. If None, a median heuristic is used (unless
+        ``sigma_vals`` is given).
+    sigma_vals : list of float or None, default=None
+        Candidate bandwidths for cross validation. If given, the bandwidth is
+        re-selected by CV, every ``cv_every`` steps.
+    cv_every : int, default=10
+        How often (in steps) to re run bandwidth cross validation.
+    dtype : torch.dtype, default=torch.float64
+        Numerical precision used throughout.
+
+    Returns
+    -------
+    list of numpy.ndarray
+        The snapshots of the particle ensemble at every step. The last element is
+        the final generated sample.
+    """
+    # device and dtype are taken from / controlled by the caller,
+    ...
+    device = X0.device 
+
+    Xt = X0.clone().to(dtype = dtype, device = device)
+    M = M.clone().to(dtype = dtype, device = device)
+    X = X_obs.to(dtype = dtype, device = device)
+
+    # determine all possible missingness patterns M
+    unique_M, inverse = torch.unique(M, dim=0, return_inverse=True)
+
+    # precompute observed indices for each m (improves computation efficiency)
+    mask_idx = {tuple(m.tolist()): (m == 1).nonzero(as_tuple=True)[0] for m in unique_M}
+
+    # samples drawn from p, i.e. conditional distribution X^(m)|M=m for different values of m
+    zpi = {m: X[inverse == i][:, mask_idx[m]].clone().to(dtype = dtype, device = device) for i,m in enumerate(mask_idx)}
+
+    # prepare cross validation for sigma
+    if sigma_vals is not None:
+        n_jobs = min(len(sigma_vals), os.cpu_count()-1)
+        kf = KFold(n_splits=3, shuffle=True, random_state=42)
+        splits_pi = {m: list(kf.split(zpi[m])) for m in mask_idx}
+        splits_rho = list(kf.split(Xt))
+
+    grads = {}
+
+    # store current sigma for each pattern m
+    if sigma_fix is None:
+        sigma_heur = sigma_heuristic_pairs(Xt)
+        sigma_current = {m: sigma_heur for m in mask_idx}
+        logger.info("Heuristic bandwidth sigma: %s", sigma_heur)
+    else:
+        sigma_current = {m: sigma_fix for m in mask_idx}
+
+    mean_grad_prev = torch.inf
+
+    Xhats = []
+    for t in tqdm(range(T), desc="WGF iterations"):
+
+        run_cv = sigma_vals is not None and t % cv_every == 0
+
+        grad_sum = 0
+        for m in mask_idx:
+            if run_cv:
+                # choose sigma by cross validation (see App. I.1 in MIRI paper)
+                logger.debug("Running CV: pattern=%s, size=%s", m, zpi[m].shape[0])
+                logger.debug("Candidate sigmas: %s", sigma_vals)
+                sigma_scores = Parallel(n_jobs=n_jobs)(
+                    delayed(evaluate_sigma)(zpi[m], Xt[:, mask_idx[m]], sig, splits_pi[m], splits_rho)
+                    for sig in sigma_vals
+                )
+                sigma_current[m] = sigma_vals[np.argmax(sigma_scores)]
+                logger.debug("Chosen sigma: %s", sigma_current[m])
+
+            # optimize (w,b) according to the objective in equation (8)
+            grads[m] = opt_wb(zpi[m], Xt[:, mask_idx[m]], Xt[:, mask_idx[m]], sigma_current[m], dtype=dtype)[0]
+
+            # enlarge grad to R^d
+            grad_full = torch.zeros_like(Xt)
+            grad_full.index_copy_(1, mask_idx[m], grads[m])
+            grad_sum += (zpi[m].shape[0]/X.shape[0]) * grad_full
+
+        # update all particles according to WGF
+        Xt = Xt + eta * grad_sum
+
+        Xhats.append(Xt.clone().cpu().numpy())
+
+        # early stopping and eta halving dependent on mean grad value
+        mean_grad = (torch.mean(torch.norm(grad_sum, dim=1)) / torch.mean(torch.norm(Xt, dim=1))).item()
+        if mean_grad < grad_tol and t+1 > min_iter:
+            logger.info("Stopped early after %d iterations (mean grad %.4f < grad_tol %s).", t+1, mean_grad, grad_tol)
+            break
+        if mean_grad > mean_grad_prev:
+            eta = eta*0.5
+            logger.info("Mean gradient increased; halving step size eta to %s.", eta)
+        mean_grad_prev = mean_grad
+
+    return Xhats

flowgem/optim.py

@@ -0,0 +1,77 @@
+"""Local linear system solver for the FLOWGEM velocity field.
+
+This module is used internally by :class:`flowgem.FlowGEM`. It computes transport
+velocity at each gradient-flow step. You normally do not need to call it directly.
+"""
+
+import torch
+
+
+def opt_wb(xpi, xrho, x, sigma, block_size=1000, dtype=torch.float64):
+    # cast inputs to the requested dtype so all internal computations are consistent
+    xpi = xpi.to(dtype)
+    xrho = xrho.to(dtype)
+    x = x.to(dtype)
+
+    n, d = x.shape
+    n_pi = xpi.shape[0]
+    n_rho = xrho.shape[0]
+
+    device = x.device
+
+    w = torch.empty(n, d, device=device, dtype=dtype)
+    b = torch.empty(n, 1, device=device, dtype=dtype)
+
+    xpi_norm = (xpi**2).sum(dim=1, keepdim=True).T  # (1,n_pi)
+    xrho_norm = (xrho**2).sum(dim=1, keepdim=True).T  # (1,n_rho)
+
+    # solve systems blockwise to ensure memory usage linear in sample size
+    # (otherwise it might crash for large n)
+    for start in range(0, n, block_size):
+        end = min(start + block_size, n)
+        xb = x[start:end]
+        bs = xb.shape[0]
+
+        xb_norm = (xb**2).sum(dim=1, keepdim=True)
+
+        # ---------- xpi kernel block ----------
+        dist2_pi = xb_norm - 2 * xb @ xpi.T + xpi_norm
+        kpix = torch.exp(-dist2_pi / (2 * sigma**2))
+
+        kpix_mean = kpix.mean(dim=1, keepdim=True)
+        Xpikpix = (kpix @ xpi) / n_pi
+
+        # ---------- xrho kernel block ----------
+        dist2_rho = xb_norm - 2 * xb @ xrho.T + xrho_norm
+        krhox = torch.exp(-dist2_rho / (2 * sigma**2))
+
+        krhox_mean = krhox.mean(dim=1, keepdim=True)
+        Xrhokrhox = (krhox @ xrho) / n_rho
+
+        # ---------- build c ----------
+        c1 = Xpikpix - Xrhokrhox
+        c2 = kpix_mean - krhox_mean
+        c = torch.cat([c1, c2], dim=1)
+
+        # ---------- build A ----------
+        ## A11 = 1/n_rho sum_{i,j} k(x_i,xrho_j) xrho_j xrho_j^T
+        A11 = torch.einsum('bk,kd,ke->bde', krhox, xrho, xrho) / n_rho
+        A12 = Xrhokrhox
+        A22 = krhox_mean.squeeze(1)
+
+        A = torch.zeros(bs, d+1, d+1, dtype=dtype, device=device)
+        A[:, :d, :d] = A11
+        A[:, :d, d] = A12
+        A[:, d, :d] = A12
+        A[:, d, d] = A22
+
+        # ---------- solve ----------
+        # regularize to avoid (near-)singular system matrices A
+        eps = 1e-5
+        A += eps * torch.eye(d+1, device=A.device)
+        res = torch.linalg.solve(A, c)
+
+        w[start:end] = res[:, :d]
+        b[start:end] = res[:, d:]
+
+    return w, b

flowgem-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: flowgem
+Version: 0.1.0
+Summary: Nonparametric generative sampling for MAR missing data via approximate Wasserstein gradient flows
+Project-URL: Homepage, https://github.com/gkremling/FLOWGEM-package
+Project-URL: Repository, https://github.com/gkremling/FLOWGEM-package
+Project-URL: Documentation, https://flowgem.readthedocs.io
+Author: Muhammad Haris Mumtaz
+Author-email: Gitte Kremling <gitte.kremling@uni-hamburg.de>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: hyperimpute>=0.1.17
+Requires-Dist: joblib>=1.5.3
+Requires-Dist: numpy>=2.5.1
+Requires-Dist: scikit-learn>=1.9.0
+Requires-Dist: torch>=2.13.0
+Requires-Dist: tqdm>=4.68.4
+Description-Content-Type: text/markdown
+
+# FLOWGEM
+
+**Generative sampling for missing data under MAR, via approximate Wasserstein gradient flows.**
+
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/gkremling/FLOWGEM-package)
+[![Python](https://img.shields.io/badge/python-3.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/gkremling/FLOWGEM-package/blob/main/LICENSE)
+
+[![Tests](https://github.com/gkremling/FLOWGEM-package/actions/workflows/ci.yml/badge.svg)](https://github.com/gkremling/FLOWGEM-package/actions)
+
+## What is FLOWGEM?
+
+FLOWGEM receives a dataset with missing values and generates a complete dataset sampled from the same distribution. It recovers the complete distribution of the data while preserving variances and correlations which keeps downstream analyses like means, quantiles, and correlations unbiased.
+
+It targets data which is **Missing at Random (MAR)**, including non-monotone MAR. It is nonparametric and makes no assumption about the shape of your data. Under the hood it uses approximate Wasserstein gradient flow which iteratively transports a particle ensemble towards target distribution.
+
+> **Note:** FLOWGEM currently supports **continuous features only**.
+> Support for categorical and mixed type data is future work.
+
+## Installation
+
+Install the released version from PyPI:
+
+```bash
+pip install flowgem
+```
+
+Or install the latest development version from GitHub:
+
+```bash
+pip install git+https://github.com/gkremling/FLOWGEM-package.git
+```
+
+## Quick start
+
+```python
+import numpy as np
+from flowgem import FlowGEM
+
+# Your data, with missing values marked as NaN
+X = np.array([
+    [1.2,    0.8,    3.1],
+    [0.5,    np.nan, 2.7],
+    [np.nan, 1.4,    2.9],
+    [2.1,    0.3,    np.nan],
+])
+
+# Fit and generate a complete sample from the same distribution
+model = FlowGEM(T=1000)
+X_complete = model.fit(X).generate()
+```
+
+`X_complete` is a fully observed array (without missing value) which is drawn from estimated data distribution.
+
+## Features
+
+- **Generative**:- generate entire dataset from the full data distribution while preserving variances and correlations.
+- **Handles non-monotone MAR**:- works with arbitrary, scattered missingness patterns.
+- **Nonparametric** :- No assumption about the shape of your data.
+- **scikit-learn-style API**:- familiar `fit` / `generate` interface.
+- **Tuning-lean**:- sensible defaults; bandwidth is set from a single heuristic
+
+## Key parameters
+
+| Parameter | What it does | Default |
+|-----------|--------------|---------|
+| `T` | number of gradient-flow steps (more = better, slower) | `1000` |
+| `eta` | step size η (smaller = finer, slower) | `0.01` |
+| `sigma` | kernel bandwidth (`None` → chosen by heuristic) | `None` |
+
+## Documentation
+
+Comprehensive and detailed documentation is available at [Read the Docs](https://flowgem.readthedocs.io).
+
+## Citation
+
+The FLOWGEM method is based on:
+
+> Kremling, G., Näf, J., & Lederer, J. (2026). *Generative Modeling under
+> Non-Monotonic MAR Missingness via Approximate Wasserstein Gradient Flows.*
+
+While using the package in course of your research, please cite this paper:
+
+```bibtex
+@article{kremling2026flowgem,
+  title   = {Generative Modeling under Non-Monotonic MAR Missingness
+             via Approximate Wasserstein Gradient Flows},
+  author  = {Kremling, Gitte and N\"af, Jeffrey and Lederer, Johannes},
+  journal = {arXiv preprint arXiv:2604.04567},
+  year    = {2026}
+}
+```
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/gkremling/FLOWGEM-package/blob/main/LICENSE) file.

flowgem-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+flowgem/__init__.py,sha256=JOa4f3f5KWX31pz0SeXZPKDsG_sbMDQVXCdRW9c1cXU,414
+flowgem/api.py,sha256=lr-OOq3ieWVH8NvDjTuECyHrC_eCIV48fPwFnfj9Egk,9557
+flowgem/bandwidth.py,sha256=bCHVcAi4ZrUgQKJrHNNxRnLwDjJtlywHtJ2AADeu5Ko,1660
+flowgem/core.py,sha256=n_LmuktsMEwTZeCE5Efbl0GCpmpHXtUIMWCN1Hv4ofk,5819
+flowgem/optim.py,sha256=qK1txg294R4J68-dHZLSD66U60t00fj2afBu90gDgNE,2476
+flowgem-0.1.0.dist-info/METADATA,sha256=14MeGJLOUncnIM_NgF-gAFuTDbkApIKgE1JpkshUFAY,4391
+flowgem-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+flowgem-0.1.0.dist-info/licenses/LICENSE,sha256=f8Hkr6vJgvmoz3XQpgGvGUefpTPpfXSkpcD7UGdZ1GA,1096
+flowgem-0.1.0.dist-info/RECORD,,

flowgem-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

flowgem-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026, Muhammad Haris Mumtaz, Gitte Kremling
+
+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.
+