mplify 1.0.0__py3-none-any.whl

mplify/DEFAULT_PARAMS.py

@@ -0,0 +1,186 @@
+"""mplify's default styling parameters — EDIT THIS FILE to change mplify's
+defaults across your project.
+
+- default_mplp_params: the base style mplp() falls back to for any parameter
+  you don't pass explicitly — fonts, spine/tick widths, colorbar, scalebar,
+  legend, etc. It's also, in effect, the 'm' / 'slide' size preset below.
+
+- SIZE_PRESETS: per-size overrides layered on top of default_mplp_params
+  when you pass size=... to mplp() (e.g. mplp(size='poster')). Aliases
+  'paper', 'slide' and 'poster' point at 's', 'm' and 'l' respectively.
+
+mplp() re-reads this file from disk (checking its mtime) on every call, so
+edits here take effect on your very next mplp() call — no kernel restart
+and no need to have %autoreload enabled.
+"""
+
+from mplify._fonts import DEFAULT_FONT_FAMILY
+
+default_mplp_params = dict(
+    # font
+    font_family=DEFAULT_FONT_FAMILY,
+
+    # title
+    title_w='regular',
+    title_s=20,
+
+    # axis labels
+    axlab_w='regular',
+    axlab_s=18,
+
+    # tick labels
+    ticklab_w='regular',
+    ticklab_s=16,
+    ticks_direction='out',
+    xlabelpad=0,
+    ylabelpad=0,
+
+    # tick rotation and alignment
+    xtickrot=0,
+    ytickrot=0,
+    xtickha='center',
+    xtickva='top',
+    ytickha='right',
+    ytickva='center',
+
+    # spines and layout
+    lw=1,
+    hide_top_right=True,
+    hide_axis=False,
+    tight_layout=False,
+    align_x_labels=True,
+    align_y_labels=True,
+
+    # legend
+    show_legend=False,
+    hide_legend=False,
+    legend_loc=(1, 1),
+
+    # figure saving
+    saveFig=False,
+    saveDir='~/Downloads',
+    figname='figure',
+    _format='pdf',
+
+    # colorbar
+    colorbar=False,
+    cbar_w=0.03,
+    cbar_h=0.4,
+    clabel=None,
+    clabel_w='regular',
+    clabel_s=18,
+    cticks_s=16,
+    cbar_pad=0.01,
+
+    # horizontal and vertical lines
+    hlines=None,
+    vlines=None,
+    lines_kwargs={'lw': 1.5, 'ls': '--', 'color': 'k', 'zorder': -1000},
+
+    # scalebar
+    xscalebar=None,
+    yscalebar=None,
+    xscalebar_unit='ms',
+    yscalebar_unit='μV',
+    scalebarkwargs={
+        'scalepad': 0.025,
+        'fontsize': 14,
+        'lw': 3,
+        'loc': 'right',
+        'offset_x': 0,
+        'offset_y': 0,
+    },
+)
+
+# Each preset scales only the "meta-plotting" elements that need to grow or
+# shrink with the viewing distance/medium — font sizes and line widths — so
+# a plot keeps the same proportions, just legible wherever it ends up.
+# Data-plotting choices (colors, markers, line styles, positions, ...) stay
+# untouched. Use via mplp(size='poster'), or import SIZE_PRESETS directly.
+SIZE_PRESETS = {
+
+    # xs: extra small — dense multi-panel figures, small insets, thumbnails
+    'xs': dict(
+        title_s=14,
+        axlab_s=13,
+        ticklab_s=11,
+        lw=0.7,
+        cbar_w=0.02,    # colorbar thickness scales with lw, else it reads as
+                        # a hairline next to xs text and a starved sliver next to xxl text
+        clabel_s=13,
+        cticks_s=9,
+        lines_kwargs={'lw': 1},
+        scalebarkwargs={'fontsize': 10, 'lw': 2},
+    ),
+
+    # s: small — paper figures, printed at a few inches wide and read up close
+    's': dict(
+        title_s=17,
+        axlab_s=15,
+        ticklab_s=14,
+        lw=0.85,
+        cbar_w=0.025,
+        clabel_s=15,
+        cticks_s=12,
+        lines_kwargs={'lw': 1.3},
+        scalebarkwargs={'fontsize': 12, 'lw': 2.5},
+    ),
+
+    # m: medium — slides, general on-screen work (mplify's original defaults)
+    'm': dict(
+        title_s=20,
+        axlab_s=18,
+        ticklab_s=16,
+        lw=1,
+        cbar_w=0.03,
+        clabel_s=18,
+        cticks_s=14,
+        lines_kwargs={'lw': 1.5},
+        scalebarkwargs={'fontsize': 14, 'lw': 3},
+    ),
+
+    # l: large — posters, read from about a meter away
+    'l': dict(
+        title_s=26,
+        axlab_s=23,
+        ticklab_s=21,
+        lw=1.3,
+        cbar_w=0.04,
+        clabel_s=23,
+        cticks_s=17,
+        lines_kwargs={'lw': 2},
+        scalebarkwargs={'fontsize': 18, 'lw': 4},
+    ),
+
+    # xl: extra large — posters/banners read from several meters away
+    'xl': dict(
+        title_s=32,
+        axlab_s=29,
+        ticklab_s=26,
+        lw=1.6,
+        cbar_w=0.05,
+        clabel_s=29,
+        cticks_s=24,
+        lines_kwargs={'lw': 2.4},
+        scalebarkwargs={'fontsize': 22, 'lw': 5},
+    ),
+
+    # xxl: banner-sized — huge posters/wall displays read from far across a room
+    'xxl': dict(
+        title_s=38,
+        axlab_s=34,
+        ticklab_s=30,
+        lw=1.9,
+        cbar_w=0.06,
+        clabel_s=34,
+        cticks_s=30,
+        lines_kwargs={'lw': 2.9},
+        scalebarkwargs={'fontsize': 27, 'lw': 6},
+    ),
+}
+
+# Semantic aliases, so you can call mplp(size='paper') instead of remembering
+# which letter size maps to which output medium.
+SIZE_PRESETS['paper'] = SIZE_PRESETS['s']    # small text, printed close-up
+SIZE_PRESETS['slide'] = SIZE_PRESETS['m']    # mplify's original defaults
+SIZE_PRESETS['poster'] = SIZE_PRESETS['l']   # large text, read from afar

mplify/__init__.py

@@ -0,0 +1,56 @@
+"""mplify: MatPlotLib prettifier"""
+
+# Snapshots for inspection at import time — mplp() itself always re-reads
+# DEFAULT_PARAMS.py fresh on every call, so edits there apply without re-importing.
+from mplify.DEFAULT_PARAMS import default_mplp_params, SIZE_PRESETS
+from mplify._core import mplp, save_mpl_fig
+from mplify._utils import set_ax_size
+from mplify._ticks import (
+    get_bestticks,
+    get_bestticks_from_array,
+    get_labels_from_ticks,
+    sci_notation,
+)
+from mplify._colors import (
+    to_rgb,
+    to_hex,
+    to_hsv,
+    get_cmap,
+    get_bounded_cmap,
+    get_ncolors_cmap,
+    get_color_families,
+    html_palette,
+)
+from mplify._colorbar import add_colorbar
+from mplify._scalebar import plot_scalebar
+
+__all__ = [
+    # Core
+    "mplp",
+    "default_mplp_params",
+    "SIZE_PRESETS",
+
+    # Save / size
+    "save_mpl_fig",
+    "set_ax_size",
+
+    # Ticks
+    "get_bestticks",
+    "get_bestticks_from_array",
+    "get_labels_from_ticks",
+    "sci_notation",
+
+    # Colors
+    "to_rgb",
+    "to_hex",
+    "to_hsv",
+    "get_cmap",
+    "get_bounded_cmap",
+    "get_ncolors_cmap",
+    "get_color_families",
+    "html_palette",
+
+    # Colorbar / scalebar
+    "add_colorbar",
+    "plot_scalebar",
+]

mplify/_colorbar.py

@@ -0,0 +1,98 @@
+"""Colorbar utilities."""
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+
+from mplify._colors import get_bounded_cmap
+from mplify._ticks import get_bestticks, get_labels_from_ticks
+
+
+def add_colorbar(fig, ax, mappable=None, vmin=None, vmax=None,
+                 width=0.01, height=0.5, cticks=None,
+                 clabel=None, clabel_w='regular', clabel_s=20, cticks_s=16,
+                 ctickslabels=None, cmap=None, center=None, pad=0.01,
+                 clim=None, cbar_ax=None):
+    """Add a colorbar to a figure, preserving the main axis size.
+
+    Either provide a mappable (e.g. the return value of ax.imshow()) or
+    provide vmin, vmax, and cmap to create one.
+
+    Arguments:
+        - fig, ax: matplotlib figure and axis
+        - mappable: a ScalarMappable (e.g. from imshow, scatter). If None,
+                    one is created from vmin/vmax/cmap.
+        - vmin, vmax: data range for the colorbar
+        - width, height: colorbar dimensions as fraction of axis size
+        - cticks: tick positions on the colorbar
+        - clabel: colorbar label text
+        - clabel_w, clabel_s: label weight and size
+        - cticks_s: tick label size
+        - ctickslabels: custom tick labels
+        - cmap: colormap name (required if mappable is None)
+        - center: center value for diverging colormaps (uses get_bounded_cmap)
+        - pad: padding between axis and colorbar as fraction of axis width
+        - clim: explicit (min, max) limits for the colorbar axis
+        - cbar_ax: pre-existing axis for the colorbar
+    """
+    # Validate vmin/vmax
+    if vmin is not None or vmax is not None:
+        if vmin is None or vmax is None:
+            raise ValueError("You must provide both vmin and vmax.")
+    if vmin is not None and vmax is not None:
+        if vmin >= vmax:
+            raise ValueError(f"vmin ({vmin}) must be less than vmax ({vmax}).")
+        if cticks is None:
+            cticks = get_bestticks(vmin, vmax, light=True)
+
+    # Create mappable if not provided
+    if mappable is None:
+        if vmin is None or vmax is None:
+            raise ValueError(
+                "Without a mappable, you must provide vmin and vmax.")
+        if cmap is None:
+            raise ValueError(
+                "Without a mappable, you must provide a colormap (e.g. 'viridis').")
+        if center is not None:
+            cmap = get_bounded_cmap(cmap, vmin, center, vmax)
+        norm = plt.Normalize(vmin, vmax)
+        mappable = plt.cm.ScalarMappable(cmap=cmap, norm=norm)
+        mappable.set_array([])
+
+    # Create colorbar axis anchored to the parent axes so it survives
+    # tight_layout / constrained_layout adjustments.
+    if cbar_ax is None:
+        cbar_ax = inset_axes(
+            ax,
+            width=f"{width * 100}%",
+            height=f"{height * 100}%",
+            loc='lower right',
+            bbox_to_anchor=(pad + width, 0, 1, 1),
+            bbox_transform=ax.transAxes,
+            borderpad=0,
+        )
+
+    fig.colorbar(mappable, cax=cbar_ax, ax=ax,
+                 orientation='vertical', label=clabel, use_gridspec=True)
+
+    # Format ticks and labels
+    if ctickslabels is None:
+        ctickslabels, _ = get_labels_from_ticks(cticks)
+    elif len(ctickslabels) != len(cticks):
+        raise ValueError(
+            f"ctickslabels length ({len(ctickslabels)}) must match "
+            f"cticks length ({len(cticks)}).")
+
+    if clabel is not None:
+        cbar_ax.yaxis.label.set_font_properties(
+            mpl.font_manager.FontProperties(weight=clabel_w, size=clabel_s))
+        cbar_ax.yaxis.label.set_rotation(-90)
+        cbar_ax.yaxis.label.set_va('bottom')
+        cbar_ax.yaxis.label.set_ha('center')
+        cbar_ax.yaxis.labelpad = 5
+    cbar_ax.yaxis.set_ticks(cticks)
+    cbar_ax.yaxis.set_ticklabels(ctickslabels, ha='left')
+    cbar_ax.yaxis.set_tick_params(pad=5, labelsize=cticks_s)
+    cbar_ax.set_ylim(clim)
+
+    return fig

mplify/_colors.py

@@ -0,0 +1,163 @@
+"""Color utilities built on top of matplotlib.colors."""
+
+import matplotlib as mpl
+import matplotlib.colors
+import numpy as np
+
+
+def to_rgb(color):
+    """Convert any matplotlib color specification to (r, g, b) tuple (0-1 range).
+
+    Accepts: named colors ('red', 'tab:blue'), hex strings ('#ff0000'),
+    single-letter codes ('r'), and RGB tuples.
+    """
+    return mpl.colors.to_rgb(color)
+
+
+def to_hex(color):
+    """Convert any matplotlib color specification to hex string.
+
+    Accepts: named colors, hex strings, single-letter codes,
+    and RGB tuples (0-1 or 0-255 range).
+    """
+    if not isinstance(color, str):
+        color = tuple(color)
+        if any(c > 1 for c in color):
+            color = tuple(c / 255 for c in color)
+    return mpl.colors.to_hex(color)
+
+
+def to_hsv(color):
+    """Convert any matplotlib color specification to HSV tuple."""
+    if isinstance(color, str):
+        color = mpl.colors.to_rgb(color)
+    return mpl.colors.rgb_to_hsv(color)
+
+
+def get_cmap(cmap_str):
+    """Get a matplotlib colormap by name."""
+    return mpl.colormaps[cmap_str]
+
+
+def get_bounded_cmap(cmap_str, vmin, center, vmax, colorseq='linear'):
+    """Create a colormap bounded around a center value.
+
+    Useful for diverging data where the center isn't at the midpoint
+    of the value range.
+
+    Arguments:
+        - cmap_str: name of a matplotlib colormap
+        - vmin, vmax: data range bounds
+        - center: center value for the colormap
+        - colorseq: 'linear' or 'nonlinear' reindexing
+    """
+    if not vmin <= center <= vmax:
+        raise ValueError(f'Must have vmin <= center <= vmax, got {vmin}, {center}, {vmax}')
+    cmap = get_cmap(cmap_str)
+
+    vrange = max(vmax - center, center - vmin)
+    if vrange == 0:
+        vrange = 1
+    if colorseq == 'linear':
+        vrange_sym = [-vrange, vrange]
+        cmin = (vmin - vrange_sym[0]) / (vrange_sym[1] - vrange_sym[0])
+        cmax = (vmax - vrange_sym[0]) / (vrange_sym[1] - vrange_sym[0])
+        colors_reindex = np.linspace(cmin, cmax, 256)
+    elif colorseq == 'nonlinear':
+        topratio = (vmax - center) / vrange
+        bottomratio = abs(vmin - center) / vrange
+        colors_reindex = np.append(
+            np.linspace(0, 0.5, int(256 * bottomratio / 2)),
+            np.linspace(0.5, 1, int(256 * topratio / 2)),
+        )
+    else:
+        raise ValueError(f"colorseq must be 'linear' or 'nonlinear', got {colorseq!r}")
+    return mpl.colors.ListedColormap(cmap(colors_reindex))
+
+
+def get_ncolors_cmap(n, cmap_str="tab10", plot=False):
+    """Return n colors homogeneously distributed from a colormap.
+
+    Arguments:
+        - n: number of colors
+        - cmap_str: name of a matplotlib colormap
+        - plot: if True, display the palette as HTML (Jupyter notebooks)
+    """
+    n = int(n)
+    cmap = get_cmap(cmap_str)
+    ids = np.linspace(0, 1, n)
+    colors = cmap(ids)[:, :-1].tolist()
+    if plot:
+        html_palette(colors)
+    return colors
+
+
+def get_color_families(ncolors, nfamilies, cmapstr=None, gap_between_families=4):
+    """Return nfamilies groups of ncolors perceptually close colors.
+
+    Within each family, colors are neighbours on a perceptually sequential colormap.
+    Between families, gap_between_families colors are skipped.
+
+    Arguments:
+        - ncolors: colors per family
+        - nfamilies: number of families
+        - cmapstr: colormap name (if None, uses matplotlib CSS colors sorted by HSV)
+        - gap_between_families: spacing between families (higher = more distinct families)
+    """
+    if cmapstr is None:
+        colors_all = _get_mpl_css_colors(sort=True, aslist=True)[15:-10]
+        indices = np.linspace(0, len(colors_all) - 1,
+                              (ncolors + gap_between_families) * nfamilies).astype(np.int64)
+        colors = np.array(colors_all)[indices].tolist()
+    else:
+        colors = get_ncolors_cmap((ncolors + gap_between_families // 2) * nfamilies,
+                                  cmapstr, plot=False)
+    highsat_colors = [c for c in colors if to_hsv(c)[1] > 0.4]
+    seed_ids = np.linspace(0, len(highsat_colors) - ncolors, nfamilies).astype(np.int64)
+    return [[highsat_colors[si + i] for i in range(ncolors)] for si in seed_ids]
+
+
+def html_palette(colors, maxwidth=20, as_str=False, show=True):
+    """Display colors as an SVG palette (works in Jupyter notebooks).
+
+    Arguments:
+        - colors: list of colors (RGB tuples, hex strings, or named colors)
+        - maxwidth: maximum colors per row
+        - as_str: if True, return raw SVG string instead of IPython HTML object
+        - show: if True, display the palette immediately
+    """
+    s = 55
+    n = min(len(colors), maxwidth)
+    col_rows = [colors[i * maxwidth:i * maxwidth + maxwidth]
+                for i in range(len(colors) // maxwidth + 1)]
+    col_rows = [c for c in col_rows if any(c)]
+    h = len(col_rows)
+    palette = f'<svg width="{n * s}" height="{s * h}">'
+    for r, row_colors in enumerate(col_rows):
+        for i, c in enumerate(row_colors):
+            c_hex = c if isinstance(c, str) else to_hex(c)
+            palette += (
+                f'<rect x="{i * s}" y="{r * s}" width="{s}" height="{s}" '
+                f'style="fill:{c_hex};stroke-width:2;stroke:rgb(255,255,255)"/>'
+            )
+    palette += '</svg>'
+    if not as_str:
+        from IPython.display import display, HTML as IPyHTML
+        palette = IPyHTML(palette)
+        if show:
+            display(palette)
+    return palette
+
+
+def _get_mpl_css_colors(sort=True, aslist=False):
+    """Get matplotlib CSS4 colors, optionally sorted by HSV."""
+    colors = mpl.colors.CSS4_COLORS
+    if sort:
+        by_hsv = sorted(
+            (tuple(mpl.colors.rgb_to_hsv(mpl.colors.to_rgb(color))), name)
+            for name, color in colors.items()
+        )
+        colors = {name: colors[name] for hsv, name in by_hsv}
+    if aslist:
+        colors = list(colors.values())
+    return colors