batplot 1.8.44__tar.gz → 1.8.46__tar.gz

{batplot-1.8.44 → batplot-1.8.46}/DEVELOPING.md

@@ -429,9 +429,23 @@ Before changing release behavior:
 
 1. Read `batplot/dev_upgrade.py`.
 2. Add or update tests in `tests/test_dev_upgrade.py`.
-3. Confirm future files are included through package discovery or manifest rules.
+3. Confirm future files are included automatically:
+   - Python modules: `packages.find include = ["batplot*"]` plus
+     `validate_distribution_contents()` (every `batplot/**/*.py` must be in the wheel).
+   - Package data: drop files into `batplot/data/` (except `USER_MANUAL.md`);
+     `--dev-upgrade` runs `sync_pyproject_package_data()` to refresh
+     `[tool.setuptools.package-data]`.
+   - Git: `_git_stage_release_snapshot()` stages tracked updates and all untracked
+     non-ignored paths (no hand-maintained file list).
 4. Keep GitHub/PyPI conflict handling explicit and testable.
 
+Canonical version files checked on every release:
+
+- `batplot/__init__.py` (`__version__`)
+- `pyproject.toml` (`[project] version`)
+- `CITATION.cff` (`version: v…`)
+- `batplot/data/latest_release_notes.json` (`version` field)
+
 ## Cross-Platform Checklist
 
 Use this checklist before finishing code changes:

batplot-1.8.46/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE DEVELOPING.md
+exclude batplot/data/USER_MANUAL.md
+include batplot/data/CHANGELOG.md
+include batplot/data/latest_release_notes.json

{batplot-1.8.44 → batplot-1.8.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batplot
-Version: 1.8.44
+Version: 1.8.46
 Summary: Interactive plotting tool for material science (1D plot) and electrochemistry (GC, CV, dQ/dV, CPC, operando) with batch processing
 Author-email: Tian Dai <tianda@uio.no>
 License: MIT License
@@ -64,9 +64,10 @@ With a single line of command to easily plot publication-ready plots with custom
 - **Electrochemistry Plot**: Galvanostatic cycling (GC), cyclic voltammetry (CV), differential capacity (dQdV), capacity per cycle (CPC) with multi-file support
 - **1D XY plot**: Designed for XRD, PDF, XAS (XANES/EXAFS) but also support other types
 - **Operando Contour plot**: Correlate in-situ characterizations (XRD/PDF/XAS) with electrochemical data
+- **Histogram mode**: Column histograms from tabular `.csv`/`.txt` data (e.g. particle-size lists)
 - **Interactive plotting**: Real-time editing customized for each type of plottings
 - **Session Persistence**: Save and reload complete plot states with `.pkl` files
-- **Style Management**: Import/export plot styles as `.bps`/`.bpsg` files
+- **Style Management**: Import/export plot styles as `.bps`/`.bpsg` files (histogram: `.bpsh`)
 - **Batch Processing**: Export each file separately with `--all`
 - **Column preview**: `--showcol` prints numbered columns, header names when found, and the first 10 values per column (CSV, Excel, text, .mpt, .brml, Bruker .raw, etc.)
 
@@ -190,6 +191,21 @@ batplot file1.xy file2.xy --stack --i
 batplot allfiles --xaxis 2theta --xrange 15 75 --i
 ```
 
+### Session save without interactive menu (`--save`)
+
+```bash
+# Single file: default .pkl name = data file stem; choose save folder when prompted
+batplot pattern.xye --xaxis 2theta --save
+
+# Batch: one session per file (default names), folder chosen once
+batplot --all --xaxis 2theta --xrange 10 80 --save
+
+# Combined plot (allfiles, operando, multi-file GC/CPC): you must name the session
+batplot allfiles --xaxis q --save
+batplot --operando --wl 0.25 --save
+batplot file1.csv file2.csv --gc --save
+```
+
 ---
 
 ## Electrochemistry Mode
@@ -296,16 +312,80 @@ Operando column selection:
 
 ---
 
+## Histogram Mode
+
+Histogram mode plots a single numeric column from tabular `.csv` or `.txt` files. It is designed for particle-size distributions and similar column data exported from spreadsheets or image-analysis tools.
+
+### Basic usage
+
+```bash
+# Interactive wizard + styling menu
+batplot sizes.csv --histo --i
+
+# Non-interactive: column, range, bins, save figure
+batplot data.txt --histo --histocol Length --xrange 0 16 --binwidth 1 --out hist.png
+
+# Preview columns before choosing
+batplot --showcol sizes.csv
+```
+
+### Startup wizard (`--i`)
+
+1. Choose the column to histogram (numbered list with preview)
+2. Set histogram range (`xmin xmax` or `auto`)
+3. Set bin width or `bins=N`
+
+### Batch export
+
+Export each CSV/TXT file in the folder as a separate figure under `Figures/`:
+
+```bash
+batplot --all --histo --histocol Length
+batplot allfiles --histo --histocol 7 --binwidth 1
+batplot histo_folder/ --histo --histocol Length
+
+# Apply a shared histogram style (.bpsh)
+batplot --all mystyle.bpsh --histo --histocol Length
+```
+
+`--histocol` is required for batch export (column number or header name).
+
+### Batch interactive editing
+
+Edit two or more histograms together (sync colors, fonts, export):
+
+```bash
+batplot allfiles --histo --i
+```
+
+If `--histocol` is omitted, the wizard runs on the first file and the same column/bin layout is reused for the rest.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--histo` | Launch histogram mode |
+| `--histocol N` | Column to histogram (1-indexed or header name) |
+| `--xrange A B` | Histogram display range |
+| `--binwidth W` | Width of each bin |
+| `--bins N` | Number of equal-width bins |
+| `--all` | Batch export each CSV/TXT file (requires `--histocol`) |
+| `allfiles` | Expand all CSV/TXT in folder (batch export or `--i` batch edit) |
+
+Style files: `.bpsh` (export with `p` in the interactive menu).
+
+---
+
 ## Plotting multiple files
 
 ```bash
 # All XY files in current directory on same figure
-batplot allfiles
-batplot allfiles --stack --i
+batplot allfiles --xaxis 2theta --i
+batplot allfiles --stack --gc --i
 
 # Only specific extension (natural-sorted)
 batplot allxyfiles
-batplot "/path/to/data" allnorfiles --i
+batplot "/path/to/data" allnorfiles --xaxis energy --i
 
 # Explicit file list
 batplot file1.xye file2.qye structure.cif:1.54 --stack --i
@@ -351,6 +431,7 @@ With `--interactive`:
 - **Styling**: Line widths, markers, fonts
 - **Axes**: Labels, limits, ticks, spine styles
 - **Export**: Sessions (`.pkl`), styles (`.bps`/`.bpsg`), high-res images. Colors persist via `p` (print style), `i` (import), `s` (save session), `b` (undo)
+- **Non-interactive session save**: `--save` (without `--i`) prompts for folder and filename—the same `.pkl` sessions as interactive `s`, with default names for single-file and `--all` batch runs
 - **Live Preview**: All changes update in real-time
 
 ---
@@ -362,6 +443,7 @@ batplot --h              # General help
 batplot --h xy           # XY mode guide
 batplot --h ec           # Electrochemistry guide
 batplot --h op           # Operando guide
+batplot --h histo        # Histogram mode guide
 batplot --v           # Version and release notes
 batplot --m            # Open illustrated manual
 ```

{batplot-1.8.44 → batplot-1.8.46}/README.md

@@ -10,9 +10,10 @@ With a single line of command to easily plot publication-ready plots with custom
 - **Electrochemistry Plot**: Galvanostatic cycling (GC), cyclic voltammetry (CV), differential capacity (dQdV), capacity per cycle (CPC) with multi-file support
 - **1D XY plot**: Designed for XRD, PDF, XAS (XANES/EXAFS) but also support other types
 - **Operando Contour plot**: Correlate in-situ characterizations (XRD/PDF/XAS) with electrochemical data
+- **Histogram mode**: Column histograms from tabular `.csv`/`.txt` data (e.g. particle-size lists)
 - **Interactive plotting**: Real-time editing customized for each type of plottings
 - **Session Persistence**: Save and reload complete plot states with `.pkl` files
-- **Style Management**: Import/export plot styles as `.bps`/`.bpsg` files
+- **Style Management**: Import/export plot styles as `.bps`/`.bpsg` files (histogram: `.bpsh`)
 - **Batch Processing**: Export each file separately with `--all`
 - **Column preview**: `--showcol` prints numbered columns, header names when found, and the first 10 values per column (CSV, Excel, text, .mpt, .brml, Bruker .raw, etc.)
 
@@ -136,6 +137,21 @@ batplot file1.xy file2.xy --stack --i
 batplot allfiles --xaxis 2theta --xrange 15 75 --i
 ```
 
+### Session save without interactive menu (`--save`)
+
+```bash
+# Single file: default .pkl name = data file stem; choose save folder when prompted
+batplot pattern.xye --xaxis 2theta --save
+
+# Batch: one session per file (default names), folder chosen once
+batplot --all --xaxis 2theta --xrange 10 80 --save
+
+# Combined plot (allfiles, operando, multi-file GC/CPC): you must name the session
+batplot allfiles --xaxis q --save
+batplot --operando --wl 0.25 --save
+batplot file1.csv file2.csv --gc --save
+```
+
 ---
 
 ## Electrochemistry Mode
@@ -242,16 +258,80 @@ Operando column selection:
 
 ---
 
+## Histogram Mode
+
+Histogram mode plots a single numeric column from tabular `.csv` or `.txt` files. It is designed for particle-size distributions and similar column data exported from spreadsheets or image-analysis tools.
+
+### Basic usage
+
+```bash
+# Interactive wizard + styling menu
+batplot sizes.csv --histo --i
+
+# Non-interactive: column, range, bins, save figure
+batplot data.txt --histo --histocol Length --xrange 0 16 --binwidth 1 --out hist.png
+
+# Preview columns before choosing
+batplot --showcol sizes.csv
+```
+
+### Startup wizard (`--i`)
+
+1. Choose the column to histogram (numbered list with preview)
+2. Set histogram range (`xmin xmax` or `auto`)
+3. Set bin width or `bins=N`
+
+### Batch export
+
+Export each CSV/TXT file in the folder as a separate figure under `Figures/`:
+
+```bash
+batplot --all --histo --histocol Length
+batplot allfiles --histo --histocol 7 --binwidth 1
+batplot histo_folder/ --histo --histocol Length
+
+# Apply a shared histogram style (.bpsh)
+batplot --all mystyle.bpsh --histo --histocol Length
+```
+
+`--histocol` is required for batch export (column number or header name).
+
+### Batch interactive editing
+
+Edit two or more histograms together (sync colors, fonts, export):
+
+```bash
+batplot allfiles --histo --i
+```
+
+If `--histocol` is omitted, the wizard runs on the first file and the same column/bin layout is reused for the rest.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--histo` | Launch histogram mode |
+| `--histocol N` | Column to histogram (1-indexed or header name) |
+| `--xrange A B` | Histogram display range |
+| `--binwidth W` | Width of each bin |
+| `--bins N` | Number of equal-width bins |
+| `--all` | Batch export each CSV/TXT file (requires `--histocol`) |
+| `allfiles` | Expand all CSV/TXT in folder (batch export or `--i` batch edit) |
+
+Style files: `.bpsh` (export with `p` in the interactive menu).
+
+---
+
 ## Plotting multiple files
 
 ```bash
 # All XY files in current directory on same figure
-batplot allfiles
-batplot allfiles --stack --i
+batplot allfiles --xaxis 2theta --i
+batplot allfiles --stack --gc --i
 
 # Only specific extension (natural-sorted)
 batplot allxyfiles
-batplot "/path/to/data" allnorfiles --i
+batplot "/path/to/data" allnorfiles --xaxis energy --i
 
 # Explicit file list
 batplot file1.xye file2.qye structure.cif:1.54 --stack --i
@@ -297,6 +377,7 @@ With `--interactive`:
 - **Styling**: Line widths, markers, fonts
 - **Axes**: Labels, limits, ticks, spine styles
 - **Export**: Sessions (`.pkl`), styles (`.bps`/`.bpsg`), high-res images. Colors persist via `p` (print style), `i` (import), `s` (save session), `b` (undo)
+- **Non-interactive session save**: `--save` (without `--i`) prompts for folder and filename—the same `.pkl` sessions as interactive `s`, with default names for single-file and `--all` batch runs
 - **Live Preview**: All changes update in real-time
 
 ---
@@ -308,6 +389,7 @@ batplot --h              # General help
 batplot --h xy           # XY mode guide
 batplot --h ec           # Electrochemistry guide
 batplot --h op           # Operando guide
+batplot --h histo        # Histogram mode guide
 batplot --v           # Version and release notes
 batplot --m            # Open illustrated manual
 ```

{batplot-1.8.44 → batplot-1.8.46}/batplot/__init__.py

@@ -7,7 +7,7 @@ import importlib.abc
 import importlib.machinery
 import sys
 
-__version__ = "1.8.44"
+__version__ = "1.8.46"
 
 
 _LEGACY_MODULE_ALIASES = {

batplot-1.8.46/batplot/_mpl_backend.py

@@ -0,0 +1,280 @@
+"""Matplotlib backend selection for batplot CLI and interactive sessions.
+
+Imported early from :mod:`batplot.cli` so pytest/CI on Windows never fall back
+to Tk when ``MPLBACKEND=Agg`` is set explicitly in the environment.
+
+When the user has not set ``MPLBACKEND``, we start on Agg for safe imports but
+may switch to a GUI backend before opening interactive windows (``.pkl`` reload,
+``--gc --i``, ``--canvas``, etc.).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+
+_USER_SET_MPLBACKEND = "MPLBACKEND" in os.environ
+_DEFAULT_BACKEND = os.environ.get("MPLBACKEND", "Agg")
+
+import matplotlib as _mpl
+
+_mpl.use(_DEFAULT_BACKEND, force=True)
+
+_INTERACTIVE_BACKENDS = frozenset(
+    {
+        "macosx",
+        "tkagg",
+        "qt5agg",
+        "qt4agg",
+        "qtagg",
+        "wxagg",
+        "gtk3agg",
+        "gtk4agg",
+        "wx",
+        "qt",
+        "gtk",
+        "gtk3",
+        "gtk4",
+    }
+)
+
+
+def _is_noninteractive_backend(name: str | None) -> bool:
+    if not isinstance(name, str):
+        return False
+    low = name.lower()
+    if low in _INTERACTIVE_BACKENDS:
+        return False
+    return ("agg" in low) or ("inline" in low) or (low in {"pdf", "ps", "svg", "template"})
+
+
+def is_interactive_backend() -> bool:
+    """Return True when the active Matplotlib backend can open a GUI window."""
+    try:
+        return not _is_noninteractive_backend(_mpl.get_backend())
+    except Exception:
+        return False
+
+
+def _headless_context() -> bool:
+    """True when batplot must stay on a non-interactive backend (CI/pytest)."""
+    if os.environ.get("BATPLOT_HEADLESS", "").lower() in ("1", "true", "yes"):
+        return True
+    if os.environ.get("CI", "").lower() in ("1", "true", "yes"):
+        return True
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        return True
+    if "pytest" in sys.modules:
+        return True
+    return False
+
+
+def running_headless() -> bool:
+    """True under pytest, CI, or when ``BATPLOT_HEADLESS`` is set."""
+    return _headless_context()
+
+
+def wants_interactive_window(args) -> bool:
+    """Return True when this CLI invocation should open an interactive figure."""
+    if args is None:
+        return False
+    if getattr(args, "all", None) is not None:
+        return False
+    files = getattr(args, "files", None) or []
+    if any(str(f).lower().endswith(".pkl") for f in files):
+        return True
+    if getattr(args, "canvas", False):
+        return True
+    if getattr(args, "interactive", False):
+        return True
+    # Headless export / session save: --out, --savefig, or --save (without --i).
+    if getattr(args, "savefig", False) or getattr(args, "out", None):
+        return False
+    if getattr(args, "save", False) and not getattr(args, "interactive", False):
+        return False
+    for attr in ("operando", "contour", "gc", "cv", "dqdv", "cpc", "epc", "histo"):
+        if getattr(args, attr, False):
+            return True
+    # Default XY / multi-file diffraction view (no --out, no --all).
+    if files:
+        return True
+    return False
+
+
+def _should_respect_env_agg() -> bool:
+    """Keep Agg when the environment requested it and we are in headless context."""
+    if not _USER_SET_MPLBACKEND:
+        return False
+    env_be = os.environ.get("MPLBACKEND")
+    if not env_be or not _is_noninteractive_backend(env_be):
+        return False
+    return _headless_context()
+
+
+def _has_qt_bindings() -> bool:
+    for mod in ("PyQt6", "PyQt5", "PySide6", "PySide2"):
+        if importlib.util.find_spec(mod) is not None:
+            return True
+    return False
+
+
+def _gui_backend_order() -> list[str]:
+    if sys.platform == "darwin":
+        return ["MacOSX", "TkAgg", "QtAgg"]
+    if sys.platform.startswith("win"):
+        return ["TkAgg", "QtAgg"]
+    return ["TkAgg", "QtAgg", "Gtk4Agg", "Gtk3Agg"]
+
+
+def _backend_can_be_tried(name: str) -> bool:
+    if name == "TkAgg":
+        return importlib.util.find_spec("tkinter") is not None
+    if name == "QtAgg":
+        return _has_qt_bindings()
+    return True
+
+
+def ensure_gui_backend(args=None) -> bool:
+    """Switch from Agg to a GUI backend when an interactive window is expected.
+
+    Returns True when the active backend is interactive (or was switched to one).
+    Honors ``MPLBACKEND=Agg`` only under pytest/CI; interactive CLI use (``--i``,
+    ``.pkl`` reload) overrides an inherited Agg default from conda/shell profiles.
+    """
+    if args is not None and not wants_interactive_window(args):
+        return is_interactive_backend()
+
+    if _should_respect_env_agg():
+        return False
+
+    if _USER_SET_MPLBACKEND:
+        env_be = os.environ.get("MPLBACKEND")
+        if env_be and not _is_noninteractive_backend(env_be):
+            return True
+
+    if is_interactive_backend():
+        return True
+
+    for cand in _gui_backend_order():
+        if not _backend_can_be_tried(cand):
+            continue
+        try:
+            _mpl.use(cand, force=True)
+            if is_interactive_backend():
+                return True
+        except Exception:
+            continue
+    return False
+
+
+def _one_line_backend_workaround() -> str:
+    """Return a copy-paste command prefix for the current platform."""
+    if sys.platform == "darwin":
+        return "MPLBACKEND=MacOSX batplot ..."
+    if sys.platform.startswith("win"):
+        return 'set MPLBACKEND=TkAgg  (cmd)  or  $env:MPLBACKEND="TkAgg"  (PowerShell), then batplot ...'
+    return "MPLBACKEND=TkAgg batplot ..."
+
+
+def _print_interactive_backend_help(context: str = "interactive menu") -> None:
+    """User-facing recovery steps when no GUI window can be opened."""
+    try:
+        backend = _mpl.get_backend()
+    except Exception:
+        backend = "unknown"
+    try:
+        from . import __version__ as _bp_version
+    except Exception:
+        _bp_version = "latest"
+
+    print()
+    print("Interactive plotting needs a display window, but batplot could not open one.")
+    print(f"(Matplotlib backend: {backend})")
+    if context:
+        print(f"This affects: {context}.")
+    print()
+    print("Try these steps, in order:")
+    print("  1. Upgrade batplot (fixes most cases):")
+    print("       pip install --upgrade batplot")
+    print(f"     You need the latest batplot release (installed: {_bp_version}).")
+    print("  2. If you cannot upgrade yet, force a GUI backend for this session:")
+    print(f"       {_one_line_backend_workaround()}")
+    print("  3. To save a figure without the interactive menu:")
+    print("       batplot ... --out figure.png   (omit --i)")
+    print()
+    print("Advanced: if MPLBACKEND=Agg is set in your shell or conda env, unset it or override")
+    print("as in step 2. On headless servers (SSH with no display), use --out instead of --i.")
+    print()
+
+
+def warn_if_noninteractive(context: str = "interactive menu") -> bool:
+    """Print a helpful message when the backend cannot show a window."""
+    if is_interactive_backend():
+        return True
+    _print_interactive_backend_help(context)
+    return False
+
+
+def require_interactive_display(
+    args=None,
+    *,
+    context: str = "interactive menu",
+    export_hint: str | None = None,
+) -> bool:
+    """Ensure a GUI backend, warn if unavailable, return True when display is possible."""
+    ensure_gui_backend(args)
+    if is_interactive_backend():
+        return True
+    warn_if_noninteractive(context)
+    return False
+
+
+def show_figure_if_possible(args=None, *, block: bool = True) -> bool:
+    """Show the current figure when the backend supports windows.
+
+    Defaults to ``block=True`` so the window stays open until the user closes it.
+    Non-interactive view mode (no ``--i``) relies on this; ``block=False`` would
+    return immediately and the process would exit before the figure is visible.
+    """
+    ensure_gui_backend(args)
+    if not is_interactive_backend():
+        if args is not None and not (getattr(args, "savefig", False) or getattr(args, "out", None)):
+            print("No display window available. Save the figure with: batplot ... --out figure.png")
+        return False
+    import matplotlib.pyplot as plt
+
+    plt.show(block=block)
+    return True
+
+
+def prime_interactive_figure(fig=None) -> None:
+    """Prepare a matplotlib window before an interactive menu (non-blocking)."""
+    import matplotlib.pyplot as plt
+
+    try:
+        plt.ion()
+    except Exception:
+        pass
+    if fig is not None:
+        try:
+            fig.canvas.draw_idle()
+            fig.canvas.flush_events()
+        except Exception:
+            pass
+    try:
+        plt.show(block=False)
+    except Exception:
+        pass
+
+
+def hold_figure_open() -> None:
+    """Keep the current figure window open until the user closes it."""
+    if not is_interactive_backend():
+        return
+    import matplotlib.pyplot as plt
+
+    try:
+        plt.show()
+    except Exception:
+        pass