vima-spatial 0.2.5__tar.gz → 0.2.7__tar.gz

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vima-spatial
-Version: 0.2.5
+Version: 0.2.7
 Summary: variational inference-based microniche analysis
 Home-page: https://github.com/yakirr/vima
 Author: Yakir Reshef

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = vima-spatial
-version = 0.2.5
+version = 0.2.7
 author = Yakir Reshef
 author_email = yreshef@broadinstitute.org
 description = variational inference-based microniche analysis

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/_settings.py

@@ -30,6 +30,19 @@ Three independent knobs:
   to verbosity (bars stay on even at ``"minimal"``); set ``False`` for batch or
   cluster runs.
 
+Plots that *are* drawn go through ``settings.show()``, which displays them when a
+display is available and otherwise saves them as PNGs. This matters on a cluster:
+with no display matplotlib falls back to the Agg backend, where ``plt.show()``
+silently discards the figure and leaves it open, so the plots are lost and the
+figures accumulate. Two knobs control the saving:
+
+* ``settings.save_plots`` -- ``"auto"`` (default) saves only when no display is
+  available, so notebooks are unaffected; ``True`` always saves (never displays),
+  ``False`` never saves.
+* ``settings.plot_dir`` -- directory for saved plots, created on demand; defaults
+  to ``"figs"``. Set to ``None`` to discard plots instead (a warning is issued
+  once).
+
 Guidelines for package code:
 
 * ``logger.info(...)``  -- normal progress messages (visible at ``default``).
@@ -39,8 +52,12 @@ Guidelines for package code:
 * ``settings.progress(iterable, name=...)`` -- wrap any loop needing a bar.
 * ``if settings.show_plots(...):`` -- guard a diagnostic plot. Pass ``"verbose"``
   for the detailed plots; the default level guards the standard ones.
+* ``settings.show(name)`` -- finish a figure. Never call ``plt.show()`` directly:
+  that displays or discards, with no way to save.
 """
 
+import os
+import re
 import sys
 import logging
 from enum import IntEnum
@@ -81,6 +98,32 @@ _LOGGING_LEVELS = {
 
 logger = logging.getLogger("vima")
 
+# matplotlib backends that render to a file and cannot display anything; a
+# terminal with no display falls back to "agg". Names are matched lowercase.
+# Fallback for the query below, and what matplotlib has reported for years.
+_FILE_ONLY_BACKENDS = {"agg", "cairo", "pdf", "pgf", "ps", "svg", "template"}
+
+
+def _file_only_backends():
+    """Names of the backends that can only write to a file.
+
+    Asked of matplotlib where it exposes the list (3.9+), so a backend added
+    later is picked up, with :data:`_FILE_ONLY_BACKENDS` as the fallback.
+
+    Deliberately phrased as "which backends are file-only" rather than "which
+    are interactive", even though matplotlib offers both: it classifies
+    Jupyter's inline backend as *non*-interactive, since it drives no GUI event
+    loop -- yet inline plots do appear in front of the user, which is the only
+    thing we need to know. ``resolve_backend`` would answer that question, but
+    it imports the backend module and raises on unknown names, so we avoid it.
+    """
+    try:
+        from matplotlib.backends.registry import backend_registry, BackendFilter
+
+        return set(backend_registry.list_builtin(BackendFilter.NON_INTERACTIVE))
+    except Exception:
+        return _FILE_ONLY_BACKENDS
+
 # ANSI colors: debug messages are grayed out, results are green.
 _GRAY, _GREEN, _RESET = "\033[90m", "\033[32m", "\033[0m"
 
@@ -135,6 +178,12 @@ class Settings:
         logger.propagate = False
 
         self.progress_bars = True
+        self.plot_dir = "figs"
+        self.save_plots = "auto"
+        self._plot_count = 0
+        self._last_figure = None
+        self._warned_plots_discarded = False
+        self._warned_save_failed = False
         self._verbosity = None
         # ``diagnostic_plots`` tracks ``verbosity`` until the user sets it.
         self._diagnostic_plots = None
@@ -174,6 +223,111 @@ class Settings:
         """
         return self._diagnostic_plots >= Verbosity.parse(level)
 
+    def _display_available(self):
+        """Whether the active matplotlib backend can actually show a figure.
+
+        A backend is a display unless it is one of the file-only ones (see
+        :func:`_file_only_backends`). Deciding it that way around means
+        anything unrecognized -- a third-party or future backend, or a
+        ``module://`` backend from an embedding host such as Jupyter's
+        ``matplotlib_inline`` or ``ipympl`` -- counts as a display, so the
+        worst case is plain ``plt.show()``, exactly as before this setting
+        existed.
+        """
+        import matplotlib
+
+        try:
+            backend = matplotlib.get_backend()
+        except Exception:  # backend resolution can fail in odd environments
+            return True
+        return backend.lower() not in _file_only_backends()
+
+    def _saving_plots(self):
+        """Whether :meth:`show` should save rather than display."""
+        if self.save_plots == "auto":
+            return not self._display_available()
+        return bool(self.save_plots)
+
+    def show(self, name=None, fig=None, overwrite=False):
+        """Display the current figure, or save it when there is no display.
+
+        Central replacement for ``plt.show()`` in package code. With a display
+        available this is exactly ``plt.show()``. Without one -- a plain
+        terminal on a cluster, where ``plt.show()`` silently discards the
+        figure *and* leaves it open, so figures pile up -- the figure is
+        written to ``settings.plot_dir`` as a PNG and closed.
+
+        ``name`` labels the file, defaulting to the name of the calling
+        function. Files are numbered in the order they are produced, so a run's
+        plots sort chronologically; pass ``overwrite=True`` to use ``name``
+        alone as the filename and replace the file on every call (for a plot
+        redrawn repeatedly, like the per-epoch training summary). ``fig`` is the
+        figure to save, defaulting to the current one -- pass it explicitly when
+        drawing onto a figure that an earlier :meth:`show` may already have
+        closed, since ``plt.gcf()`` would then hand back a blank one.
+
+        Returns the path written, or ``None`` if the figure was displayed or
+        discarded.
+        """
+        import matplotlib.pyplot as plt
+
+        if fig is None:
+            fig = plt.gcf()
+        self._last_figure = fig
+
+        if not self._saving_plots():
+            plt.show()
+            return None
+
+        if self.plot_dir is None:
+            if not self._warned_plots_discarded:
+                logger.warning(
+                    "no display available and vima.settings.plot_dir is None, so "
+                    "plots are being discarded; set vima.settings.plot_dir to save "
+                    "them as images instead"
+                )
+                self._warned_plots_discarded = True
+            plt.close(fig)
+            return None
+
+        if name is None:
+            name = sys._getframe(1).f_code.co_name
+        name = re.sub(r"[^0-9a-zA-Z]+", "_", str(name)).strip("_").lower() or "plot"
+        if overwrite:
+            filename = f"{name}.png"
+        else:
+            self._plot_count += 1
+            filename = f"{self._plot_count:03d}_{name}.png"
+
+        path = os.path.join(self.plot_dir, filename)
+        try:
+            os.makedirs(self.plot_dir, exist_ok=True)
+            fig.savefig(path, dpi=150, bbox_inches="tight")
+        except OSError as e:
+            # A diagnostic plot is never worth aborting a long run for.
+            if not self._warned_save_failed:
+                logger.warning(f"could not save plot to {path}: {e}")
+                self._warned_save_failed = True
+            plt.close(fig)
+            return None
+        plt.close(fig)
+        logger.info(f"saved plot to {path}")
+        return path
+
+    def current_figure(self):
+        """The figure a follow-up call should draw on.
+
+        Normally ``plt.gcf()``. When plots are being saved instead of shown,
+        :meth:`show` closes each figure, so ``plt.gcf()`` would hand back a
+        fresh blank one; with no figure open, return the last figure
+        :meth:`show` handled instead.
+        """
+        import matplotlib.pyplot as plt
+
+        if not plt.get_fignums() and self._last_figure is not None:
+            return self._last_figure
+        return plt.gcf()
+
     def progress(self, iterable=None, name=None, total=None, ncols=100, desc=None, **kwargs):
         """tqdm wrapper honoring ``settings.progress_bars``.
 

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/ingest/dimreduce.py

@@ -91,7 +91,7 @@ def metapixels_allsamples(normedpixelsdir, masksdir, sids, total_n_metapixels):
         plt.xlabel('# non-empty pixels per metapixel')
         plt.ylabel('Frequency')
         plt.tight_layout()
-        plt.show()
+        settings.show('metapixel_occupancy_cdf')
 
     return all_metapixels, all_npixels
 
@@ -174,7 +174,7 @@ def pca_metapixels(mps, k):
         plt.imshow(loadings, cmap='seismic', vmin=-0.5, vmax=0.5)
         plt.yticks(range(len(loadings)), loadings.index)
         plt.xticks(range(len(loadings.columns)), loadings.columns, rotation=90)
-        plt.show()
+        settings.show('pc_loadings')
 
     return loadings, C, allmp
 

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/ingest/ingest.py

@@ -65,9 +65,10 @@ def visualize_pixels(pixels, ntoplot, input, colorby):
         if settings.show_plots('verbose'):
             sns.scatterplot(x='PC1', y='PC2', hue=metavar, data=toplot, palette='Set1', s=1, legend=False)
             plt.title(metavar)
-            plt.show()
+            settings.show(f'pc1_pc2_by_{metavar}')
         sc.pl.umap(toplot_ad, color=metavar, legend_loc=None, frameon=False,
-                   title=f'pixels UMAPed using {input}, colored by {metavar}')
+                   title=f'pixels UMAPed using {input}, colored by {metavar}', show=False)
+        settings.show(f'pixel_umap_by_{metavar}')
         
         # print LISI ratio
         n_unique = toplot_ad.obs[metavar].nunique()
@@ -250,7 +251,7 @@ def sanity_checks(outdir, repname, npcs=1, nskip=3):
     s = da.astype(np.float32)
     da.close(); del da
     s.plot(col='marker', col_wrap=5, vmin=-10, vmax=10, cmap='seismic')
-    plt.show()
+    settings.show(f'all_pcs_{sids[0]}')
     del s
 
     logger.info('histogram of each pc')
@@ -270,7 +271,7 @@ def sanity_checks(outdir, repname, npcs=1, nskip=3):
         plt.subplot(int(np.ceil(nmms/4)), 4, i+1)
         plt.hist(harmpixels[:,i], bins=1000)
     plt.tight_layout()
-    plt.show()
+    settings.show('pc_histograms')
     del harmpixels
     gc.collect()
 
@@ -290,4 +291,4 @@ def sanity_checks(outdir, repname, npcs=1, nskip=3):
             ax.set_title(sid)
             del s; gc.collect()
         plt.tight_layout()
-        plt.show()
+        settings.show(f'pc{i}_by_sample')

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/ingest/st.py

@@ -115,7 +115,8 @@ def get_sumstats(load, filepaths, target_sum, x_col, y_col, gene_col, n_top_gene
                 hvgs = hvgs + list(set(genes_to_add) & set(pl.var_names))
                 
                 if settings.show_plots():
-                    sc.pl.highly_variable_genes(pl, log=True, show=True)
+                    sc.pl.highly_variable_genes(pl, log=True, show=False)
+                    settings.show(f'hvgs_{sid}')
 
                 if settings.show_plots('verbose'):
                     top8 = (
@@ -144,7 +145,7 @@ def get_sumstats(load, filepaths, target_sum, x_col, y_col, gene_col, n_top_gene
                         ax.set_aspect('equal')
                         ax.axis('off')
                     plt.tight_layout()
-                    plt.show()
+                    settings.show(f'top_hvgs_{sid}')
                     plt.close(fig)
 
                 union_hvgs.update(hvgs)
@@ -220,7 +221,8 @@ def transcriptlist_to_normedpixelmatrix(sid, data, x_col, y_col, gene_col, pixel
     pl = pl[(pl[markers].sum(axis=1) >= min_ntranscripts_per_pixel) ]#& (pl[list(set(markers) & set(genes))].sum(axis=1) > 0)]
     if settings.show_plots():
         plt.scatter(pl.pixel_x, pl.pixel_y, c=pl[markers].sum(axis=1), s=0.1, alpha=0.8, vmin=0, vmax=100)
-        plt.gca().set_aspect('equal'); plt.title('transcript density (gray = failed qc)'); plt.axis('off'); plt.show()
+        plt.gca().set_aspect('equal'); plt.title('transcript density (gray = failed qc)'); plt.axis('off')
+        settings.show(f'transcript_density_{sid}')
     logger.info(f'\t{len(pl)} pixels after QC.')
 
     logger.info('\tLog-normalizing...')

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/train/logging.py

@@ -4,6 +4,7 @@ import time
 import matplotlib.pyplot as plt
 from IPython import display
 from .. import vis as v
+from .._settings import settings
 
 class LossLogger:
     """Accumulate and report per-model training/validation losses; returned by `train`."""
@@ -118,7 +119,9 @@ class LossLogger:
         plt.title('Reconstruction error across validation patches')
         plt.xlabel('Reconstruction error'); plt.ylabel('#Patches')
         plt.gca().spines[['top', 'right']].set_visible(False)
-        plt.show()
+        # Redrawn every epoch, so keep overwriting one file rather than
+        # accumulating one per epoch.
+        settings.show('training_progress', overwrite=True)
 
         if self.detailed:
             ix = np.argsort(vrlosses)

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/vis/features.py

@@ -2,6 +2,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 import seaborn as sns
+from .._settings import settings
 
 
 def _select_features(features, group_a, group_b, n_top, n_bottom, markers):
@@ -49,6 +50,11 @@ def plot_features(
         ``[label_a, label_b]`` for the legend.
     kind
         'violin' (default), 'box', or 'swarm'.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure that was drawn.
     """
     if ax is None:
         ax = plt.gca()
@@ -70,7 +76,8 @@ def plot_features(
     plot_kwargs.update(kwargs)
     plot_fn(data=df, x='marker', y='value', hue='status', order=toplot, ax=ax, **plot_kwargs)
     if show:
-        plt.show()
+        settings.show()
+    return ax.figure
 
 
 def plot_features_by_sample(
@@ -114,6 +121,11 @@ def plot_features_by_sample(
         ``[label_a, label_b]`` for the legend.
     connect
         Draw lines linking each sample's two group means.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure that was drawn.
     """
     if ax is None:
         ax = plt.gca()
@@ -147,4 +159,5 @@ def plot_features_by_sample(
                         color='gray', alpha=0.4, lw=0.8, zorder=0)
 
     if show:
-        plt.show()
+        settings.show()
+    return ax.figure

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/vis/patches.py

@@ -30,7 +30,7 @@ def _plot_separate(patches, markers, vmin, vmax, cmap='seismic', show=True):
         axes[k, 0].set_ylabel(marker, fontsize=9)
     plt.tight_layout()
     if show:
-        plt.show()
+        settings.show()
     return fig
 
 
@@ -94,7 +94,7 @@ def _plot_composite(patches, markers, colors, vmin, vmax, features=None, nx=5, n
     if subfig is None:
         plt.tight_layout(rect=[0, 0.08, 1, 1])
     if show:
-        plt.show()
+        settings.show()
     return fig
 
 
@@ -441,5 +441,5 @@ def show_patches_cells(patchmeta, cells, x_col, y_col, celltype_col,
         plt.tight_layout(rect=[0, bottom_margin, 1, 1])
 
     if show:
-        plt.show()
+        settings.show()
     return fig

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/vis/patchexamples.py

@@ -4,6 +4,7 @@ import torch
 import scanpy as sc
 from scipy.optimize import linear_sum_assignment
 from mpl_toolkits.axes_grid1.anchored_artists import AnchoredSizeBar
+from .._settings import settings
 
 
 def scaler(minimum=0, maximum=255):
@@ -52,7 +53,8 @@ def plot_with_reconstruction(model, examples, show=True, channels=[0,1,2], pmin=
 
     if show:
         plt.tight_layout()
-        plt.show()
+        settings.show()
+    return fig
 
 
 def plot_patches_separatechannels(examples, choose=None, vmax=10, vmin=None, channels=[0,1,2], channelnames=None):
@@ -74,7 +76,8 @@ def plot_patches_separatechannels(examples, choose=None, vmax=10, vmin=None, cha
                 plt.gca().text(-5, 20, channelnames[j], va='center', ha='right', rotation=90)
 
     plt.tight_layout()
-    plt.show()
+    settings.show()
+    return fig
 
 
 # colormaps consists of tuples of the form [channel, color, scaler]
@@ -83,8 +86,6 @@ def plot_patches_overlaychannels(examples, colormaps, nx=5, ny=5, show=True, see
         if seed is not None: np.random.seed(seed)
         ix = np.random.choice(range(len(examples)), size=nx*ny, replace=False)
         examples = examples[ix]
-    else:
-        ix = range(len(examples))
 
     images = apply_colormap(examples, colormaps)
 
@@ -95,8 +96,8 @@ def plot_patches_overlaychannels(examples, colormaps, nx=5, ny=5, show=True, see
         plt.axis('off')
     plt.tight_layout()
     if show:
-        plt.show()
-    return ix
+        settings.show()
+    return fig
 
 
 def plot_patches_overlaychannels_linsum(patches, latents, colormaps, nx=5, ny=5, show=True, seed=None,
@@ -144,9 +145,8 @@ def plot_patches_overlaychannels_linsum(patches, latents, colormaps, nx=5, ny=5,
         axs[-1,-1].add_artist(scalebar)
 
     if show:
-        plt.show()
-    else:
-        return fig
+        settings.show()
+    return fig
 
 
 def plot_patches_overlaychannels_sorted(examples, colormaps, labels=None, nx=5, ny=5, show=True):
@@ -161,7 +161,8 @@ def plot_patches_overlaychannels_sorted(examples, colormaps, labels=None, nx=5,
         plt.axis('off')
     plt.tight_layout()
     if show:
-        plt.show()
+        settings.show()
+    return fig
 
 
 # each color channel should be a tuple of the form (channel, scaler)
@@ -178,4 +179,4 @@ def plot_patches_fourcolors(examples, nx=5, ny=5,
     if yellow[0] is not None:
         colormaps.append([yellow[0], [1,1,0], yellow[1]])
 
-    plot_patches_overlaychannels(examples, colormaps, nx=nx, ny=ny, show=show)
+    return plot_patches_overlaychannels(examples, colormaps, nx=nx, ny=ny, show=show)

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/vis/spatial.py

@@ -20,6 +20,11 @@ def plot_sample_with_patches(s, marker, patchmeta, remove_margin=False, ax=None,
         Patch metadata; patches belonging to this sample are outlined.
     remove_margin
         Crop to a margin around the outlined patches.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure that was drawn.
     """
     if ax is None: ax = plt.gca()
 
@@ -48,7 +53,8 @@ def plot_sample_with_patches(s, marker, patchmeta, remove_margin=False, ax=None,
     ax.set_ylim(y_max, y_min)
 
     if show:
-        plt.show()
+        settings.show()
+    return ax.figure
 
 
 def plot_samples_with_patches(samples, marker, patchmeta, ncols=5, **kwargs):
@@ -63,6 +69,11 @@ def plot_samples_with_patches(samples, marker, patchmeta, ncols=5, **kwargs):
         Marker to display.
     patchmeta
         Patch metadata; patches are outlined on their sample.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure that was drawn.
     """
     nrows = int(np.ceil(len(samples) / ncols))
     fig, axs = plt.subplots(nrows, ncols, figsize=(3*ncols, 3*nrows))
@@ -70,7 +81,8 @@ def plot_samples_with_patches(samples, marker, patchmeta, ncols=5, **kwargs):
         plot_sample_with_patches(s, marker, patchmeta, ax=ax, show=False, **kwargs)
         ax.set_title(s.sid)
     fig.tight_layout()
-    fig.show()
+    settings.show(fig=fig)
+    return fig
 
 
 def plot_npatches_per_sample(samples, patchmeta):
@@ -79,17 +91,23 @@ def plot_npatches_per_sample(samples, patchmeta):
 
     Samples in `samples` with no patches in `patchmeta` are shown with a count
     of zero.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure that was drawn.
     """
     res = patchmeta.sid.value_counts()
     empty = [sid for sid in samples.keys() if sid not in patchmeta.sid.unique()]
     for sid in empty:
         res.loc[sid] = 0
 
-    plt.figure(figsize=(15,2))
+    fig = plt.figure(figsize=(15,2))
     plt.bar(x=res.index, height=res)
     plt.tick_params(axis='x', rotation=90)
     plt.gca().spines[['top', 'right']].set_visible(False)
-    plt.show()
+    settings.show()
+    return fig
 
 
 def _adjust_resolution(mypatches):
@@ -185,7 +203,7 @@ def spatialplot(patchmeta, values, sids=None, cmap='viridis', vmin=None, vmax=No
     fig._vima_sid_to_ax = sid_to_ax
     fig.tight_layout()
     if show:
-        plt.show()
+        settings.show()
     return fig
 
 
@@ -205,7 +223,7 @@ def annotate_spatialplot(patchmeta, highlight, color, thickness=3, show=True, fi
         Figure returned by `spatialplot`; defaults to the current figure.
     """
     if fig is None:
-        fig = plt.gcf()
+        fig = settings.current_figure()
     sid_to_ax = fig._vima_sid_to_ax
     for sid, ax in sid_to_ax.items():
         mypatches = patchmeta[patchmeta.sid == sid]
@@ -234,5 +252,5 @@ def annotate_spatialplot(patchmeta, highlight, color, thickness=3, show=True, fi
             ax.plot(np.append(cnt[:, 0], cnt[0, 0]), np.append(cnt[:, 1], cnt[0, 1]), color=color, linewidth=thickness)
 
     if show:
-        plt.show()
+        settings.show(fig=fig)
     return fig

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima/vis/umaps.py

@@ -1,5 +1,6 @@
 import matplotlib.pyplot as plt
 import scanpy as sc
+from .._settings import settings
 
 
 def plot_association(D, key='mncoef', fdr_thresh=0.1, ax=None, show=True, **kwargs):
@@ -17,6 +18,11 @@ def plot_association(D, key='mncoef', fdr_thresh=0.1, ax=None, show=True, **kwar
         Coefficient column in ``D.obs`` (with matching ``{key}_fdr``).
     fdr_thresh
         FDR cutoff for calling a microniche significant.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure that was drawn.
     """
     if ax is None:
         ax = plt.gca()
@@ -34,4 +40,5 @@ def plot_association(D, key='mncoef', fdr_thresh=0.1, ax=None, show=True, **kwar
         plt.title(f'No significant microniches at FDR {fdr_thresh*100:.0f}%')
         
     if show:
-        plt.show()
+        settings.show()
+    return ax.figure

{vima_spatial-0.2.5 → vima_spatial-0.2.7}/src/vima_spatial.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vima-spatial
-Version: 0.2.5
+Version: 0.2.7
 Summary: variational inference-based microniche analysis
 Home-page: https://github.com/yakirr/vima
 Author: Yakir Reshef