batplot 1.8.45__tar.gz → 1.8.46__tar.gz

{batplot-1.8.45 → 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.45 → batplot-1.8.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batplot
-Version: 1.8.45
+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.45 → 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.45 → batplot-1.8.46}/batplot/__init__.py

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

{batplot-1.8.45 → batplot-1.8.46}/batplot/_mpl_backend.py

@@ -77,6 +77,8 @@ def running_headless() -> bool:
 
 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 []
@@ -86,12 +88,17 @@ def wants_interactive_window(args) -> bool:
         return True
     if getattr(args, "interactive", False):
         return True
-    # Headless export: mode flags with --out/--savefig do not need a GUI window.
+    # Headless export / session save: --out, --savefig, or --save (without --i).
     if getattr(args, "savefig", False) or getattr(args, "out", None):
         return False
-    for attr in ("operando", "contour", "gc", "cv", "dqdv", "cpc", "epc"):
+    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
 
 
@@ -128,26 +135,6 @@ def _backend_can_be_tried(name: str) -> bool:
     return True
 
 
-def _backend_setup_tips() -> list[str]:
-    if sys.platform == "darwin":
-        return [
-            "  export MPLBACKEND=MacOSX   # built-in macOS backend",
-            "  export MPLBACKEND=TkAgg    # if Tk is available",
-            "  export MPLBACKEND=QtAgg    # if PyQt/PySide is installed",
-        ]
-    if sys.platform.startswith("win"):
-        return [
-            "  set MPLBACKEND=TkAgg        # cmd, if Tk is available",
-            '  $env:MPLBACKEND="TkAgg"   # PowerShell',
-            "  set MPLBACKEND=QtAgg        # if PyQt/PySide is installed",
-        ]
-    return [
-        "  export MPLBACKEND=TkAgg     # if python3-tk is installed",
-        "  export MPLBACKEND=QtAgg     # if PyQt/PySide is installed",
-        "  export MPLBACKEND=Gtk3Agg  # if GTK3 bindings are installed",
-    ]
-
-
 def ensure_gui_backend(args=None) -> bool:
     """Switch from Agg to a GUI backend when an interactive window is expected.
 
@@ -181,20 +168,51 @@ def ensure_gui_backend(args=None) -> bool:
     return False
 
 
-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
+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"
-    print(f"Matplotlib backend '{backend}' is non-interactive; a window cannot be shown.")
-    print("Tips: unset MPLBACKEND or set a GUI backend:")
-    for line in _backend_setup_tips():
-        print(line)
+    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"The {context} requires an interactive backend.")
+        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
 
 
@@ -202,30 +220,61 @@ def require_interactive_display(
     args=None,
     *,
     context: str = "interactive menu",
-    export_hint: str | None = "Or run without --interactive and use --out to save the figure.",
+    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)
-    if export_hint:
-        print(export_hint)
     return False
 
 
-def show_figure_if_possible(args=None, *, block: bool = False) -> bool:
-    """Show the current figure when the backend supports windows."""
+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)):
-            try:
-                backend = _mpl.get_backend()
-            except Exception:
-                backend = "unknown"
-            print(f"Matplotlib backend '{backend}' is non-interactive; use --out to save the figure.")
+            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