wellerlab 0.1.0__tar.gz

wellerlab-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: wellerlab
+Version: 0.1.0
+Summary: WellerLab Orange3 suite: Metabo statistics, PLS-DA/OPLS-DA, PCA Pro and NMR preprocessing in one category
+Author: Philipp Weller
+Author-email: philipp.weller@googlemail.com
+Project-URL: Source, https://github.com/philippweller/WellerLab/tree/main/orange-wellerlab-addon
+Project-URL: Bug Tracker, https://github.com/philippweller/WellerLab/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Description-Content-Type: text/markdown
+
+# wellerlab — WellerLab Orange3 Suitepack
+
+Alle Werkzeuge des Weller-Labors in **einem** Orange3-Add-on und **einer**
+Kategorie: **Weller Lab**.
+
+| Familie | Widgets | Inhalt |
+|---|---|---|
+| `wellerlab.metabo` | Metabo Feature Table, Preprocess, Feature Filter, Univariate Stats, Heatmap, Volcano | MetaboAnalyst-artige Statistik für GC-MS/GC-IMS-Feature-Tables (Compound Discoverer). Qt-freier Kern `metabo_core`. |
+| `wellerlab.plsda` | PLS-DA, OPLS-DA | Multivariate Klassifikation; OPLS-DA mit S-Plot (p1/p(corr)), Schwellen, Farbcodierung, Klick/Shift-Klick-Selektion, VIP + orthoVIP, R2X/R2Y/Q2 (7-fach-CV) und Permutationstest. Qt-freier Kern `opls_core`. |
+| `wellerlab.pca` | PCA Pro | Chemometrische PCA: Scaling (none/center/Pareto/autoscale), Komponentenwahl (Kaiser, Varianzanteil, feste Zahl), Hotelling-T²- und Q-Residuen-Diagnostik. |
+| `wellerlab.nmr` | NMR Baseline Correction, Binning (Bucketing), Region Exclusion, Filter (Savitzky-Golay), Normalization, Reference & Alignment | Vorverarbeitung von NMR-Spektren. |
+
+## Installation
+
+```bash
+# aus dem Monorepo (empfohlen): findet Oranges eigenes Python
+python orange-install.py wellerlab
+
+# oder direkt
+/Applications/Orange.app/Contents/MacOS/python -m pip install wellerlab
+```
+
+Beim ersten Start danach erscheint die Kategorie **Weller Lab** mit allen
+Widgets. Wichtig: frühere Einzelpakete (`orangemetabo`, `orangeplsda`,
+`orangepca`, `orangenmr`) müssen entfernt sein, sonst erscheinen die Widgets
+doppelt.
+
+## Icons
+
+Ein generiertes, konsistentes Set: gleiche Kachelform und Strichstärke,
+Familienfarbe und -glyphe (Chromatogramm = Metabo, Multiplett = NMR,
+latente Ellipsen = PLS/OPLS, Score-Plot = PCA) plus Kurzlabel.
+Erzeugt von `tools/gen_icons.py` im Monorepo.
+
+## Tests (headless, offscreen)
+
+Kanonischer Befehl — findet Oranges Python selbst und läuft mit *jedem* Python:
+
+```bash
+python3 run_tests.py                     # alle Suiten
+python3 run_tests.py --python /pfad/zum/python
+```
+
+Die drei Suiten einzeln:
+
+```bash
+PY=/Applications/Orange.app/Contents/MacOS/python
+$PY _test_opls_core.py      # Numerik: R2Y/Q2/VIP/Permutation
+$PY _test_owoplsda.py       # Widget: Schwellen, Farben, Selektion, Ausgänge
+$PY _test_suite.py          # Integration: alle 15 Widgets, Icons, Kategorie
+```
+
+> **macOS/Apple-Silicon-Falle:** Wird Oranges universeller Interpreter von einem
+> x86_64-Python (Rosetta, z. B. einer Intel-conda-Installation) gestartet, läuft er
+> selbst als x86_64 — dort scheitert der Import von Oranges arm64-only
+> numpy-Extension („you should not try to import numpy from its source
+> directory“). `run_tests.py` umgeht das automatisch mit `arch -arm64`; bei
+> direkten Aufrufen nativ starten oder ebenfalls `arch -arm64` voranstellen.
+
+## Lizenz
+
+MIT · Philipp Weller · philipp.weller@googlemail.com

wellerlab-0.1.0/README.md

@@ -0,0 +1,62 @@
+# wellerlab — WellerLab Orange3 Suitepack
+
+Alle Werkzeuge des Weller-Labors in **einem** Orange3-Add-on und **einer**
+Kategorie: **Weller Lab**.
+
+| Familie | Widgets | Inhalt |
+|---|---|---|
+| `wellerlab.metabo` | Metabo Feature Table, Preprocess, Feature Filter, Univariate Stats, Heatmap, Volcano | MetaboAnalyst-artige Statistik für GC-MS/GC-IMS-Feature-Tables (Compound Discoverer). Qt-freier Kern `metabo_core`. |
+| `wellerlab.plsda` | PLS-DA, OPLS-DA | Multivariate Klassifikation; OPLS-DA mit S-Plot (p1/p(corr)), Schwellen, Farbcodierung, Klick/Shift-Klick-Selektion, VIP + orthoVIP, R2X/R2Y/Q2 (7-fach-CV) und Permutationstest. Qt-freier Kern `opls_core`. |
+| `wellerlab.pca` | PCA Pro | Chemometrische PCA: Scaling (none/center/Pareto/autoscale), Komponentenwahl (Kaiser, Varianzanteil, feste Zahl), Hotelling-T²- und Q-Residuen-Diagnostik. |
+| `wellerlab.nmr` | NMR Baseline Correction, Binning (Bucketing), Region Exclusion, Filter (Savitzky-Golay), Normalization, Reference & Alignment | Vorverarbeitung von NMR-Spektren. |
+
+## Installation
+
+```bash
+# aus dem Monorepo (empfohlen): findet Oranges eigenes Python
+python orange-install.py wellerlab
+
+# oder direkt
+/Applications/Orange.app/Contents/MacOS/python -m pip install wellerlab
+```
+
+Beim ersten Start danach erscheint die Kategorie **Weller Lab** mit allen
+Widgets. Wichtig: frühere Einzelpakete (`orangemetabo`, `orangeplsda`,
+`orangepca`, `orangenmr`) müssen entfernt sein, sonst erscheinen die Widgets
+doppelt.
+
+## Icons
+
+Ein generiertes, konsistentes Set: gleiche Kachelform und Strichstärke,
+Familienfarbe und -glyphe (Chromatogramm = Metabo, Multiplett = NMR,
+latente Ellipsen = PLS/OPLS, Score-Plot = PCA) plus Kurzlabel.
+Erzeugt von `tools/gen_icons.py` im Monorepo.
+
+## Tests (headless, offscreen)
+
+Kanonischer Befehl — findet Oranges Python selbst und läuft mit *jedem* Python:
+
+```bash
+python3 run_tests.py                     # alle Suiten
+python3 run_tests.py --python /pfad/zum/python
+```
+
+Die drei Suiten einzeln:
+
+```bash
+PY=/Applications/Orange.app/Contents/MacOS/python
+$PY _test_opls_core.py      # Numerik: R2Y/Q2/VIP/Permutation
+$PY _test_owoplsda.py       # Widget: Schwellen, Farben, Selektion, Ausgänge
+$PY _test_suite.py          # Integration: alle 15 Widgets, Icons, Kategorie
+```
+
+> **macOS/Apple-Silicon-Falle:** Wird Oranges universeller Interpreter von einem
+> x86_64-Python (Rosetta, z. B. einer Intel-conda-Installation) gestartet, läuft er
+> selbst als x86_64 — dort scheitert der Import von Oranges arm64-only
+> numpy-Extension („you should not try to import numpy from its source
+> directory“). `run_tests.py` umgeht das automatisch mit `arch -arm64`; bei
+> direkten Aufrufen nativ starten oder ebenfalls `arch -arm64` voranstellen.
+
+## Lizenz
+
+MIT · Philipp Weller · philipp.weller@googlemail.com

wellerlab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wellerlab-0.1.0/setup.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+
+from setuptools import setup, find_packages
+
+HERE = Path(__file__).parent
+
+README = HERE / "README.md"
+long_description = (README.read_text(encoding="utf-8") if README.exists()
+                    else "WellerLab Orange3 tool suite: metabolomics feature-table "
+                         "statistics, PLS-DA/OPLS-DA, PCA Pro and NMR preprocessing.")
+
+setup(
+    name="wellerlab",
+    version="0.1.0",
+    description="WellerLab Orange3 suite: Metabo statistics, PLS-DA/OPLS-DA, "
+                "PCA Pro and NMR preprocessing in one category",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    packages=find_packages(include=["wellerlab", "wellerlab.*"]),
+    include_package_data=True,
+    author="Philipp Weller",
+    author_email="philipp.weller@googlemail.com",
+    install_requires=[
+        "Orange3>=3.40.0",
+        "numpy",
+        "scipy",
+        "matplotlib",
+        "scikit-learn",
+        "pandas",
+    ],
+    entry_points={
+        "orange.widgets": (
+            "Weller Lab = wellerlab.widgets",
+        ),
+    },
+    package_data={
+        "wellerlab": ["widgets/icons/*.svg",
+                      "metabo/widgets/icons/*.svg",
+                      "plsda/widgets/icons/*.svg",
+                      "pca/widgets/icons/*.svg",
+                      "nmr/widgets/icons/*.svg"],
+    },
+    project_urls={
+        "Source": "https://github.com/philippweller/WellerLab/tree/main/orange-wellerlab-addon",
+        "Bug Tracker": "https://github.com/philippweller/WellerLab/issues",
+    },
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Topic :: Scientific/Engineering",
+    ],
+)

wellerlab-0.1.0/wellerlab/__init__.py

@@ -0,0 +1,17 @@
+"""
+WellerLab — the complete Orange3 tool suite of the Weller lab.
+
+One distribution, one Orange category ("Weller Lab"):
+
+    wellerlab.metabo  MetaboAnalyst-style feature-table statistics
+                      (import, preprocess, filter, univariate, heatmap, volcano)
+    wellerlab.plsda   PLS-DA and OPLS-DA (S-plot, VIP, Q2, permutation)
+    wellerlab.pca     PCA Pro
+    wellerlab.nmr     NMR preprocessing (baseline, binning, exclusion,
+                      filter, normalization, reference)
+
+The numerical cores (``metabo.metabo_core``, ``plsda.opls_core``) are free of
+Qt/Orange and can be imported and tested headlessly.
+"""
+
+__version__ = "0.1.0"

wellerlab-0.1.0/wellerlab/metabo/__init__.py

@@ -0,0 +1,3 @@
+"""wellerlab.metabo — MetaboAnalyst-style add-on for Orange3."""
+
+__version__ = "0.4.4"

wellerlab-0.1.0/wellerlab/metabo/metabo_core.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+MetaboAnalyst-style univariate statistics core for GC-MS / GC-IMS
+feature tables (Compound Discoverer exports).
+
+This module is the analytics heart of the wellerlab.metabo add-on. It is
+deliberately free of any Qt / Orange dependency so it can be unit-tested
+headlessly with plain numpy/scipy. The widgets in `orangemetabo/widgets/`
+are thin GUI wrappers around the functions here.
+
+Pipeline (matches the validated ground truth `cv_anova_alle_97_features.csv`,
+97/97 features on F, p and FDR_BH):
+
+    load -> sum-normalise -> log2 -> autoscale (z-score per feature)
+         -> univariate statistics (one-way ANOVA / Welch t / Kruskal-Wallis)
+         -> Benjamini-Hochberg FDR
+
+All functions are pure: they take arrays / lists and return DataFrames or
+arrays. No file I/O except the optional `load_feature_table` reader.
+"""
+import csv
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+
+# --------------------------------------------------------------------------
+# Feature-table reader (Compound Discoverer 2-header semicolon CSV)
+# --------------------------------------------------------------------------
+
+def load_feature_table(path):
+    """Read a Compound Discoverer feature-table CSV.
+
+    Expected layout (semicolon-separated, UTF-8-BOM):
+      row 0: "" , "Area: <sample>.raw", ...
+      row 1: "" , "<group>",           ...
+      row 2+: "<feature name>", values...
+
+    Returns (feature_names: list[str], samples: list[str],
+             groups: list[str], X: np.ndarray[features x samples]).
+    """
+    with open(path, encoding="utf-8-sig", newline="") as f:
+        rows = list(csv.reader(f, delimiter=";"))
+    samples = [h.replace("Area: ", "").replace(".raw", "").strip()
+               for h in rows[0][1:]]
+    groups = [g.strip() for g in rows[1][1:]]
+    feat = [r[0].strip() for r in rows[2:]]
+    X = np.array(
+        [[float(v) for v in r[1:1 + len(samples)]] for r in rows[2:]],
+        dtype=float,
+    )
+    return feat, samples, groups, X
+
+
+# --------------------------------------------------------------------------
+# Preprocessing
+# --------------------------------------------------------------------------
+
+def normalize_sum(X):
+    """Total-area (sum) normalisation: rescale each sample column so that
+    every column has the mean of the column totals."""
+    col_sums = X.sum(axis=0)
+    return X / col_sums * col_sums.mean()
+
+
+def log2_transform(X):
+    """log2 with a guard against non-positive values (clip to tiny eps)."""
+    eps = np.finfo(float).tiny
+    return np.log2(np.clip(X, eps, None))
+
+
+def impute_low(X, threshold=0.05, method="knn", k=3):
+    """Impute below-threshold values (fraction of column min or a hard cap).
+
+    Methods:
+      'constant' : replace with the column minimum (or 0).
+      'min'      : replace with the column minimum.
+      'knn'      : replace with the mean of the k nearest samples in the
+                   Euclidean distance of the non-imputed rows.
+    Returns (X_imputed, imputed_mask).
+    """
+    X = np.asarray(X, dtype=float).copy()
+    col_min = X.min(axis=0)
+    mask = X < (col_min * (1 + threshold))
+    if not mask.any():
+        return X, mask
+    if method in ("constant", "min"):
+        rows, cols = np.nonzero(mask)
+        X[rows, cols] = col_min[cols]
+        return X, mask
+    # knn: distance between samples (columns) over all feature rows;
+    # impute each flagged value with the mean of its k nearest samples.
+    n_rows, n_cols = X.shape
+    d = np.sqrt(((X[:, :, None] - X[:, None, :]) ** 2).sum(axis=0))  # c x c
+    np.fill_diagonal(d, np.inf)
+    order = d.argsort(axis=1)
+    for c in range(n_cols):
+        bad = np.nonzero(mask[:, c])[0]
+        if bad.size == 0:
+            continue
+        for r in bad:
+            # prefer samples that are not flagged on this same feature
+            nb = order[c, :max(k, 1)]
+            ok = [j for j in nb if not (mask[r, j] and j != c)]
+            if not ok:
+                X[r, c] = col_min[c]
+            else:
+                X[r, c] = X[r, ok].mean()
+    return X, mask
+
+
+def scale_rows(X, method="autoscale"):
+    """Per-feature (row) scaling.
+
+      'autoscale' : z-score (mean 0, std 1, ddof=1)
+      'pareto'    : (x - mean) / sqrt(std)
+      'none'      : unchanged
+    Constant rows are returned as zeros (division guard).
+    """
+    X = np.asarray(X, dtype=float)
+    mean = X.mean(axis=1, keepdims=True)
+    if method == "none":
+        return X
+    std = X.std(axis=1, keepdims=True, ddof=1)
+    denom = np.where(std > 0, np.sqrt(std) if method == "pareto" else std, 1.0)
+    return (X - mean) / denom
+
+
+# --------------------------------------------------------------------------
+# Multiple-testing correction
+# --------------------------------------------------------------------------
+
+def bh_fdr(p):
+    """Benjamini-Hochberg FDR for an array of p-values."""
+    p = np.asarray(p, dtype=float)
+    m = len(p)
+    if m == 0:
+        return p
+    order = p.argsort()
+    ranked = p[order]
+    q = np.minimum.accumulate((ranked * m / np.arange(1, m + 1))[::-1])[::-1]
+    qf = np.empty(m)
+    qf[order] = np.clip(q, 0, 1)
+    return qf
+
+
+# --------------------------------------------------------------------------
+# Univariate statistics
+# --------------------------------------------------------------------------
+
+def _groups_arrays(X, groups, levels):
+    """Yield the per-group column slices for every feature row."""
+    gi = {lv: np.array(groups) == lv for lv in levels}
+    return [X[:, idx] for idx in gi.values()]
+
+
+def univariate(X, groups, method="anova", base=None, treats=None,
+               feature_names=None):
+    """Run the selected univariate test for every feature row.
+
+    method:
+      'anova' : one-way ANOVA across all levels (>= 2 levels, >= 2 per level).
+      'welch' : Welch two-sample t-test, `treats` combined vs `base`.
+      'kruskal': one-way Kruskal-Wallis across all levels.
+
+    feature_names: optional list of row labels (same length as X rows);
+      when given, the `Feature` column holds these names, else row indices.
+
+    Returns (DataFrame, levels). The DataFrame has columns
+      Feature, stat, p, (log2FC for welch), FDR_BH,
+      sorted by ascending p.
+    """
+    X = np.asarray(X, dtype=float)
+    groups = list(groups)
+    levels = list(dict.fromkeys(groups))
+    n = X.shape[0]
+    names = list(feature_names) if feature_names is not None else list(range(n))
+    res = []
+    if method in ("anova", "kruskal"):
+        for i in range(n):
+            cols = [X[i, np.array(groups) == lv] for lv in levels]
+            if any(c.size < 2 for c in cols):
+                stat, p = np.nan, np.nan
+            elif method == "anova":
+                stat, p = stats.f_oneway(*cols)
+            else:
+                stat, p = stats.kruskal(*cols)
+            res.append(dict(Feature=names[i], stat=stat, p=p))
+    elif method == "welch":
+        if base not in levels or not treats:
+            raise ValueError("Welch test needs `base` and non-empty `treats`.")
+        b = np.array(groups) == base
+        a = np.isin(np.array(groups), treats)
+        for i in range(n):
+            if X[i, a].size < 2 or X[i, b].size < 2:
+                stat, p = np.nan, np.nan
+                fc = np.nan
+            else:
+                stat, p = stats.ttest_ind(X[i, a], X[i, b], equal_var=False)
+                fc = X[i, a].mean() - X[i, b].mean()
+            res.append(dict(Feature=names[i], stat=stat, p=p, log2FC=fc))
+    else:
+        raise ValueError(f"unknown method {method!r}")
+
+    df = pd.DataFrame(res)
+    df["p"] = pd.Series(df["p"]).astype(float)
+    df = df.sort_values("p", na_position="last").reset_index(drop=True)
+    df["FDR_BH"] = bh_fdr(df["p"].values)
+    return df, levels
+
+
+def add_group_means(df, X, groups, levels, feature_names=None):
+    """Append per-group mean columns (on the supplied, usually scaled, X).
+
+    `df` must contain a `Feature` column. When `feature_names` is given it
+    maps feature names to their row index in X; otherwise `Feature` values
+    are assumed to already be row indices.
+    """
+    X = np.asarray(X, dtype=float)
+    groups = np.asarray(groups)
+    out = df.copy()
+    if feature_names is not None:
+        name_to_row = {n: i for i, n in enumerate(feature_names)}
+    else:
+        name_to_row = None
+    for lv in levels:
+        vals = []
+        for f in out["Feature"]:
+            i = name_to_row.get(f) if name_to_row is not None else f
+            vals.append(
+                X[i, groups == lv].mean() if (groups == lv).any() else np.nan)
+        out[f"mean_{lv}"] = vals
+    return out
+
+
+def format_p(v):
+    """Human-friendly p-value string (scientific below 1e-4)."""
+    if v is None or (isinstance(v, float) and np.isnan(v)):
+        return "NA"
+    if v < 1e-4:
+        return f"{v:.2e}"
+    return f"{v:.4f}"
+
+
+# --------------------------------------------------------------------------
+# Volcano (contrast derived from per-group means)
+# --------------------------------------------------------------------------
+
+def volcano_table(df, group_a, group_b, fdr_col="FDR_BH", alpha=0.05, fc=1.0):
+    """Build a volcano table for the contrast `group_a` vs `group_b`.
+
+    Operates on a univariate results frame (as produced by `univariate` +
+    `add_group_means`): it needs a `Feature` column, the two `mean_<group>`
+    columns and an FDR column. Group means live in the (log2) space the data
+    was supplied in, so the fold change is their difference:
+
+        log2FC = mean_a - mean_b      (positive => higher in group_a)
+
+    Returns a DataFrame with columns
+      Feature, log2FC, FDR_BH, neglog10FDR, direction,
+    where direction is "up"  (FDR < alpha and log2FC >=  fc),
+                     "down"(FDR < alpha and log2FC <= -fc),
+                     "ns"  otherwise.
+    """
+    ca, cb = f"mean_{group_a}", f"mean_{group_b}"
+    for c in ("Feature", ca, cb, fdr_col):
+        if c not in df.columns:
+            raise ValueError(f"volcano needs column {c!r}")
+    lfc = df[ca].to_numpy(float) - df[cb].to_numpy(float)
+    fdr = df[fdr_col].to_numpy(float)
+    out = pd.DataFrame({
+        "Feature": df["Feature"].to_numpy(),
+        "log2FC": lfc,
+        "FDR_BH": fdr,
+        "neglog10FDR": -np.log10(np.clip(fdr, np.finfo(float).tiny, None)),
+    })
+    sig = fdr < alpha
+    out["direction"] = np.where(
+        sig & (lfc >= fc), "up",
+        np.where(sig & (lfc <= -fc), "down", "ns"))
+    return out

wellerlab-0.1.0/wellerlab/metabo/widgets/__init__.py

@@ -0,0 +1,17 @@
+"""Widget definitions for wellerlab.metabo."""
+
+from .owfeatureimport import OWFeatureImport  # noqa: F401
+from .owpreprocess import OWMetaboPreprocess  # noqa: F401
+from .owfeaturefilter import OWFeatureFilter  # noqa: F401
+from .owunivariate import OWUnivariateStats  # noqa: F401
+from .owheatmap import OWMetaboHeatmap  # noqa: F401
+from .owvolcano import OWVolcano  # noqa: F401
+
+__all__ = [
+    "OWFeatureImport",
+    "OWMetaboPreprocess",
+    "OWFeatureFilter",
+    "OWUnivariateStats",
+    "OWMetaboHeatmap",
+    "OWVolcano",
+]

wellerlab-0.1.0/wellerlab/metabo/widgets/_dialogs.py

@@ -0,0 +1,37 @@
+"""Small Qt dialog helpers shared by the Metabo widgets.
+
+Orange's ``Orange.widgets.utils.filedialogs`` API is not stable across
+releases: the ``OpenFileDialog`` / ``SaveFileDialog`` classes used by older
+widgets no longer exist in current Orange (they were replaced by the
+``open_filename_dialog`` / ``open_filename_dialog_save`` functions). To stay
+working on every Orange version the widgets call plain ``QFileDialog``
+directly through these two helpers — one idiom, no version-specific imports.
+"""
+
+
+def open_feature_table(parent, start_dir=""):
+    """Ask for a feature-table CSV/TXT. Returns a path or None (cancelled)."""
+    from AnyQt.QtWidgets import QFileDialog
+    path, _ = QFileDialog.getOpenFileName(
+        parent, "Open feature table", start_dir or "",
+        "Feature table (*.csv *.txt *.tsv);;All files (*)")
+    return path or None
+
+
+def save_figure(parent, fig, kind="PNG"):
+    """Ask for a path and write figure `fig` as PNG (dpi 300) or SVG.
+
+    `kind` is 'PNG' or 'SVG' (case-insensitive). Returns the path written,
+    or None if the user cancelled.
+    """
+    from AnyQt.QtWidgets import QFileDialog
+    kind = kind.upper()
+    ext = ".png" if kind == "PNG" else ".svg"
+    path, _ = QFileDialog.getSaveFileName(
+        parent, f"Save figure ({kind})", "", f"{kind} (*{ext});;All files (*)")
+    if not path:
+        return None
+    if not path.lower().endswith(ext):
+        path += ext
+    fig.savefig(path, dpi=300 if kind == "PNG" else None, facecolor="white")
+    return path