batplot 1.8.55__tar.gz → 1.8.57__tar.gz

{batplot-1.8.55 → batplot-1.8.57}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batplot
-Version: 1.8.55
+Version: 1.8.57
 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
@@ -85,7 +85,7 @@ pip install batplot
 ## Quick Start
 
 - User manual: https://chem-plot.github.io/batplot/
-- Tutorial: https://drive.google.com/file/d/1NTFJWNBbWW4mgz0H5ZelGjuOBWxoFgkr/view
+- Tutorial videos: https://www.youtube.com/watch?v=gnX1ytqlV4k&list=PLaJaXAfs1irk
 - Demo files: https://github.com/chem-plot/batplot/blob/main/batplot_demo_files.zip
 
 ---
@@ -491,7 +491,8 @@ With `--interactive`:
 
 ## Help & Documentation
 
-Illustrated user manual (GitHub Pages): https://chem-plot.github.io/batplot/
+- Illustrated user manual: https://chem-plot.github.io/batplot/
+- Tutorial videos: https://www.youtube.com/watch?v=gnX1ytqlV4k&list=PLaJaXAfs1irk
 
 ```bash
 batplot --h              # General help

{batplot-1.8.55 → batplot-1.8.57}/README.md

@@ -29,7 +29,7 @@ pip install batplot
 ## Quick Start
 
 - User manual: https://chem-plot.github.io/batplot/
-- Tutorial: https://drive.google.com/file/d/1NTFJWNBbWW4mgz0H5ZelGjuOBWxoFgkr/view
+- Tutorial videos: https://www.youtube.com/watch?v=gnX1ytqlV4k&list=PLaJaXAfs1irk
 - Demo files: https://github.com/chem-plot/batplot/blob/main/batplot_demo_files.zip
 
 ---
@@ -435,7 +435,8 @@ With `--interactive`:
 
 ## Help & Documentation
 
-Illustrated user manual (GitHub Pages): https://chem-plot.github.io/batplot/
+- Illustrated user manual: https://chem-plot.github.io/batplot/
+- Tutorial videos: https://www.youtube.com/watch?v=gnX1ytqlV4k&list=PLaJaXAfs1irk
 
 ```bash
 batplot --h              # General help

{batplot-1.8.55 → batplot-1.8.57}/batplot/__init__.py

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

{batplot-1.8.55 → batplot-1.8.57}/batplot/args.py

@@ -201,6 +201,7 @@ def _print_general_help() -> None:
         "  Personal page: https://www.mn.uio.no/kjemi/english/people/aca/tianda/\n"
         "  GitHub: https://github.com/chem-plot/batplot\n"
         "  User manual: https://chem-plot.github.io/batplot/\n"
+        "  Tutorial videos: https://www.youtube.com/watch?v=gnX1ytqlV4k&list=PLaJaXAfs1irk\n"
         "  Kindly cite Tian's github page if the plot is used for publication\n"
         )
     _print_help(msg)

{batplot-1.8.55 → batplot-1.8.57}/batplot/data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.8.56] - 2026-09-25
+- Add normalization suppor for dQdV mode
+
+
+## [1.8.57] - 2026-09-25
+- Bug fixes
+
+
 ## [1.8.55] - 2026-09-15
 - Bug fixes
 

{batplot-1.8.55 → batplot-1.8.57}/batplot/data/latest_release_notes.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.55",
+  "version": "1.8.57",
   "custom_message": "- Bug fixes",
   "update_notes": [
     "- Bug fixes"

{batplot-1.8.55 → batplot-1.8.57}/batplot/plot_modes/batch_session/ec_batch_helpers.py

@@ -55,6 +55,7 @@ __all__ = [
     "apply_ec_line_chrome_only",
     "apply_ec_scoped_sync",
     "apply_ec_smooth_only",
+    "apply_ec_norm_only",
     "apply_ec_spine_colors_only",
     "apply_ec_wasd_chrome_only",
     "default_ec_tick_state",
@@ -526,6 +527,39 @@ def apply_ec_smooth_only(panel: EcPanel, cfg: dict, *, silent: bool = True) -> b
     return True
 
 
+def apply_ec_norm_only(panel: EcPanel, cfg: dict, *, silent: bool = True) -> bool:
+    """Batch ``nm`` (dQdV): sync normalize settings and re-apply (not colors / WASD)."""
+    from ..electrochem.dqdv_norm import apply_dqdv_norm, reset_dqdv_norm
+
+    cfg = dict(cfg) if isinstance(cfg, dict) else {}
+    norm = cfg.get("_dqdv_norm_settings")
+    if not isinstance(norm, dict):
+        return False
+    file_data, cycle_lines, is_multi = ec_normalize_file_data(panel)
+    try:
+        if bool(norm.get("enabled")):
+            apply_dqdv_norm(
+                panel.fig,
+                file_data=file_data if is_multi else None,
+                cycle_lines=cycle_lines,
+                method=norm.get("method"),
+                visible_only=False,
+                ax=panel.ax,
+            )
+        else:
+            reset_dqdv_norm(
+                panel.fig,
+                file_data=file_data if is_multi else None,
+                cycle_lines=cycle_lines,
+                ax=panel.ax,
+            )
+    except Exception as exc:
+        if not silent:
+            print(f"dQ/dV normalize sync failed for {getattr(panel, 'path', '?')}: {exc}")
+        return False
+    return True
+
+
 def ec_panel_is_dqdv(panel: EcPanel) -> bool:
     """True when this EC panel is a dQ/dV (differential capacity) session."""
     ax = getattr(panel, "ax", None)

{batplot-1.8.55 → batplot-1.8.57}/batplot/plot_modes/batch_session/menu_ec.py

@@ -82,6 +82,7 @@ from .ec_batch_helpers import (
     apply_ec_legend_only,
     apply_ec_line_chrome_only,
     apply_ec_smooth_only,
+    apply_ec_norm_only,
     apply_ec_spine_colors_only,
     apply_ec_wasd_chrome_only,
     default_ec_tick_state,
@@ -103,6 +104,7 @@ from .ec_batch_helpers import (
 from ..electrochem.interactive import _apply_stored_smooth_settings
 from ..electrochem.legend_order import run_ec_legend_order_menu
 from ..electrochem.smoothing_menu import run_dqdv_smoothing_menu
+from ..electrochem.dqdv_norm import run_dqdv_norm_menu
 from .load import EcPanel
 
 
@@ -140,6 +142,8 @@ def _print_ec_batch_menu(panels: List[EcPanel]) -> None:
     ]
     if is_dqdv:
         col1.insert(2, "sm: smooth")
+        # Batch: normalize each panel (multi-file overlay or peer single-file panels).
+        col1.insert(3, "nm: normalize")
     if _ec_batch_has_multi_file(panels):
         # Match interactive: only list file visibility when multi-file
         col1.insert(-1, "v: show/hide files")
@@ -389,10 +393,76 @@ def run_ec_batch_menu(panels: List[EcPanel]) -> None:
                     safe_input=safe_input,
                     colorize_menu=_colorize_menu,
                     colorize_prompt=colorize_prompt,
+                    ax=ref.ax,
                 ),
             )
             continue
 
+        if cmd == "nm":
+            if not is_dqdv:
+                print("'nm' is only available in batch dQ/dV mode.")
+                continue
+            file_data, cycle_lines, is_multi_file, print_file_list = _ref_menu_context(ref)
+            # Interactive nm requires multi-file on the ref panel; for single-file
+            # batch peers, apply normalize directly then sync settings.
+            def _edit_nm() -> None:
+                if is_multi_file and file_data and len(file_data) >= 2:
+                    run_dqdv_norm_menu(
+                        fig=ref.fig,
+                        ax=ref.ax,
+                        cycle_lines=cycle_lines,
+                        file_data=file_data,
+                        current_file_idx=0,
+                        all_cycles=ec_all_cycles(cycle_lines, file_data),
+                        is_dqdv=True,
+                        is_multi_file=True,
+                        menu_title="",
+                        canvas_mode=False,
+                        print_menu=lambda *_a, **_k: None,
+                        print_file_list=print_file_list,
+                        push_state=noop_snapshot,
+                        safe_input=safe_input,
+                        colorize_menu=_colorize_menu,
+                        colorize_prompt=colorize_prompt,
+                    )
+                else:
+                    from ..electrochem.dqdv_norm import (
+                        apply_dqdv_norm,
+                        format_dqdv_norm_status,
+                        reset_dqdv_norm,
+                    )
+
+                    print("\n" + format_dqdv_norm_status(ref.fig))
+                    print("  a: normalize this panel  |  r: reset  |  q: back")
+                    sub = safe_input(colorize_prompt("Normalize (a/r/q): ")).strip().lower()
+                    if sub in ("a", "all"):
+                        apply_dqdv_norm(
+                            ref.fig,
+                            file_data=None,
+                            cycle_lines=cycle_lines,
+                            ax=ref.ax,
+                        )
+                        print("Normalized.")
+                    elif sub == "r":
+                        reset_dqdv_norm(
+                            ref.fig,
+                            file_data=None,
+                            cycle_lines=cycle_lines,
+                            ax=ref.ax,
+                        )
+                        print("Normalize reset.")
+
+            edit_ref_then_sync(
+                ref,
+                panels,
+                undo=undo,
+                capture_panel=_capture_panel,
+                apply_cfg=apply_ec_norm_only,
+                draw_all=lambda: draw_panels(panels),
+                edit_fn=_edit_nm,
+            )
+            continue
+
         if cmd == "t":
             run_ec_batch_spine_menu(
                 ref,

batplot-1.8.57/batplot/plot_modes/electrochem/dqdv_norm.py

@@ -0,0 +1,419 @@
+"""Multi-file dQ/dV Y-normalization (instrument-agnostic).
+
+Works on already-plotted ``Line2D`` data after Neware / BioLogic / CS-B /
+numerical loaders. Default method ``max_abs`` scales each file so
+``max(|y|) == 1`` across that file's charge+discharge curves — useful when
+overlaying absolute ``dQ/dV`` with specific ``dQm/dV`` exports.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional, Sequence
+
+import numpy as np
+
+
+_NORM_ATTR_PRE = "_dqdv_pre_norm_ydata"
+_NORM_ATTR_APPLIED = "_dqdv_norm_applied"
+_NORM_ATTR_SCALE = "_dqdv_norm_scale"
+
+DEFAULT_METHOD = "max_abs"
+
+
+def default_dqdv_norm_settings() -> Dict[str, Any]:
+    return {
+        "enabled": False,
+        "method": DEFAULT_METHOD,
+        # Parallel to file_data when multi-file; empty when off.
+        "file_scales": [],
+    }
+
+
+def get_dqdv_norm_settings(fig) -> Dict[str, Any]:
+    raw = getattr(fig, "_dqdv_norm_settings", None)
+    if not isinstance(raw, dict):
+        return default_dqdv_norm_settings()
+    out = default_dqdv_norm_settings()
+    out["enabled"] = bool(raw.get("enabled", False))
+    method = raw.get("method") or DEFAULT_METHOD
+    out["method"] = str(method) if method else DEFAULT_METHOD
+    scales = raw.get("file_scales")
+    if isinstance(scales, (list, tuple)):
+        try:
+            out["file_scales"] = [float(x) for x in scales]
+        except (TypeError, ValueError):
+            out["file_scales"] = []
+    return out
+
+
+def set_dqdv_norm_settings(fig, settings: Optional[dict]) -> None:
+    if not isinstance(settings, dict) or not settings:
+        fig._dqdv_norm_settings = default_dqdv_norm_settings()
+        return
+    fig._dqdv_norm_settings = {
+        "enabled": bool(settings.get("enabled", False)),
+        "method": str(settings.get("method") or DEFAULT_METHOD),
+        "file_scales": list(settings.get("file_scales") or []),
+    }
+
+
+def format_dqdv_norm_status(fig) -> str:
+    cfg = get_dqdv_norm_settings(fig)
+    if not cfg.get("enabled"):
+        return "Current: normalize off"
+    method = cfg.get("method") or DEFAULT_METHOD
+    scales = cfg.get("file_scales") or []
+    if scales:
+        bits = ", ".join(f"{i + 1}:{s:.4g}" for i, s in enumerate(scales))
+        return f"Current: normalize on ({method}); scales [{bits}]"
+    return f"Current: normalize on ({method})"
+
+
+def _iter_lines(cycle_lines) -> Iterable[Any]:
+    if not isinstance(cycle_lines, dict):
+        return
+    for _cyc, parts in cycle_lines.items():
+        if isinstance(parts, dict):
+            for role in ("charge", "discharge"):
+                ln = parts.get(role)
+                if ln is not None:
+                    yield ln
+        elif parts is not None:
+            yield parts
+
+
+def _clear_line_norm_attrs(ln) -> None:
+    for attr in (_NORM_ATTR_PRE, _NORM_ATTR_APPLIED, _NORM_ATTR_SCALE):
+        if hasattr(ln, attr):
+            try:
+                delattr(ln, attr)
+            except Exception:
+                pass
+
+
+def clear_norm_attrs_on_cycle_lines(cycle_lines) -> None:
+    for ln in _iter_lines(cycle_lines):
+        _clear_line_norm_attrs(ln)
+
+
+def _restore_pre_norm_y(ln) -> bool:
+    if not bool(getattr(ln, _NORM_ATTR_APPLIED, False)):
+        return False
+    pre = getattr(ln, _NORM_ATTR_PRE, None)
+    if pre is None:
+        return False
+    try:
+        ln.set_ydata(np.asarray(pre, float))
+        ln._dqdv_norm_applied = False
+        return True
+    except Exception:
+        return False
+
+
+def _peak_abs(y: np.ndarray) -> float:
+    if y.size == 0:
+        return 0.0
+    finite = y[np.isfinite(y)]
+    if finite.size == 0:
+        return 0.0
+    return float(np.max(np.abs(finite)))
+
+
+def _normalize_cycle_lines(cycle_lines, *, method: str = DEFAULT_METHOD) -> float:
+    """Normalize one file's curves in place. Returns the scale factor used."""
+    lines = list(_iter_lines(cycle_lines))
+    if not lines:
+        return 1.0
+    for ln in lines:
+        _restore_pre_norm_y(ln)
+    bases: List[np.ndarray] = []
+    for ln in lines:
+        y = np.asarray(ln.get_ydata(), float).copy()
+        setattr(ln, _NORM_ATTR_PRE, y)
+        bases.append(y)
+    if method not in (DEFAULT_METHOD, "max_abs"):
+        method = DEFAULT_METHOD
+    peak = 0.0
+    for y in bases:
+        peak = max(peak, _peak_abs(y))
+    scale = (1.0 / peak) if peak > 0.0 else 1.0
+    for ln, y in zip(lines, bases):
+        try:
+            ln.set_ydata(y * scale)
+            setattr(ln, _NORM_ATTR_APPLIED, True)
+            setattr(ln, _NORM_ATTR_SCALE, float(scale))
+        except Exception:
+            pass
+    return float(scale)
+
+
+def reset_cycle_lines_norm(cycle_lines) -> int:
+    """Restore pre-norm Y on one file's curves. Returns restored line count."""
+    n = 0
+    for ln in _iter_lines(cycle_lines):
+        if _restore_pre_norm_y(ln):
+            n += 1
+        _clear_line_norm_attrs(ln)
+    return n
+
+
+def _targets_from_file_data(
+    file_data: Optional[Sequence[dict]],
+    cycle_lines,
+    file_indices: Optional[Sequence[int]],
+    *,
+    visible_only: bool,
+) -> List[tuple]:
+    """Return list of (file_index_or_None, cycle_lines)."""
+    if file_data and len(file_data) > 0:
+        out = []
+        if file_indices is None:
+            idxs = list(range(len(file_data)))
+        else:
+            idxs = [int(i) for i in file_indices]
+        for i in idxs:
+            if i < 0 or i >= len(file_data):
+                continue
+            f = file_data[i]
+            if visible_only and not bool(f.get("visible", True)):
+                continue
+            cl = f.get("cycle_lines")
+            if isinstance(cl, dict):
+                out.append((i, cl))
+        return out
+    if isinstance(cycle_lines, dict):
+        return [(None, cycle_lines)]
+    return []
+
+
+def apply_dqdv_norm(
+    fig,
+    *,
+    file_data: Optional[Sequence[dict]] = None,
+    cycle_lines=None,
+    file_indices: Optional[Sequence[int]] = None,
+    method: Optional[str] = None,
+    visible_only: bool = True,
+    update_ylabel: bool = True,
+    ax=None,
+) -> Dict[str, Any]:
+    """Apply per-file max_|y| normalization. Returns updated settings dict."""
+    cfg = get_dqdv_norm_settings(fig)
+    use_method = str(method or cfg.get("method") or DEFAULT_METHOD)
+    targets = _targets_from_file_data(
+        file_data, cycle_lines, file_indices, visible_only=visible_only
+    )
+    if not targets:
+        return cfg
+
+    n_files = len(file_data) if file_data else 1
+    scales = list(cfg.get("file_scales") or [])
+    while len(scales) < n_files:
+        scales.append(1.0)
+    if file_data:
+        scales = scales[:n_files]
+
+    for idx, cl in targets:
+        scale = _normalize_cycle_lines(cl, method=use_method)
+        if idx is not None and 0 <= idx < len(scales):
+            scales[idx] = scale
+        elif idx is None:
+            scales = [scale]
+
+    cfg = {
+        "enabled": True,
+        "method": use_method,
+        "file_scales": scales if file_data else [scales[0] if scales else 1.0],
+    }
+    set_dqdv_norm_settings(fig, cfg)
+
+    if update_ylabel and ax is not None:
+        try:
+            if not hasattr(ax, "_dqdv_ylabel_before_norm"):
+                ax._dqdv_ylabel_before_norm = ax.get_ylabel()
+            ax.set_ylabel("normalized dQ/dV (a.u.)")
+            ax._stored_ylabel = "normalized dQ/dV (a.u.)"
+        except Exception:
+            pass
+    try:
+        fig.canvas.draw_idle()
+    except Exception:
+        pass
+    return cfg
+
+
+def reset_dqdv_norm(
+    fig,
+    *,
+    file_data: Optional[Sequence[dict]] = None,
+    cycle_lines=None,
+    file_indices: Optional[Sequence[int]] = None,
+    restore_ylabel: bool = True,
+    ax=None,
+) -> int:
+    """Restore pre-norm Y. Returns number of restored lines."""
+    targets = _targets_from_file_data(
+        file_data, cycle_lines, file_indices, visible_only=False
+    )
+    n = 0
+    for _idx, cl in targets:
+        n += reset_cycle_lines_norm(cl)
+    set_dqdv_norm_settings(fig, default_dqdv_norm_settings())
+    if restore_ylabel and ax is not None:
+        try:
+            prev = getattr(ax, "_dqdv_ylabel_before_norm", None)
+            if isinstance(prev, str):
+                ax.set_ylabel(prev)
+                ax._stored_ylabel = prev
+            if hasattr(ax, "_dqdv_ylabel_before_norm"):
+                delattr(ax, "_dqdv_ylabel_before_norm")
+        except Exception:
+            pass
+    try:
+        fig.canvas.draw_idle()
+    except Exception:
+        pass
+    return n
+
+
+def reapply_dqdv_norm_after_data_change(
+    fig,
+    *,
+    file_data: Optional[Sequence[dict]] = None,
+    cycle_lines=None,
+    ax=None,
+) -> None:
+    """After smooth/filter changes Y, rebase and re-apply if normalize is on."""
+    cfg = get_dqdv_norm_settings(fig)
+    if not cfg.get("enabled"):
+        return
+    targets = _targets_from_file_data(
+        file_data, cycle_lines, None, visible_only=False
+    )
+    for _idx, cl in targets:
+        clear_norm_attrs_on_cycle_lines(cl)
+    apply_dqdv_norm(
+        fig,
+        file_data=file_data,
+        cycle_lines=cycle_lines,
+        file_indices=None,
+        method=cfg.get("method"),
+        visible_only=False,
+        update_ylabel=True,
+        ax=ax,
+    )
+
+
+def run_dqdv_norm_menu(
+    *,
+    fig,
+    ax,
+    cycle_lines,
+    file_data,
+    current_file_idx,
+    all_cycles,
+    is_dqdv,
+    is_multi_file,
+    menu_title,
+    canvas_mode,
+    print_menu,
+    print_file_list,
+    push_state,
+    safe_input,
+    colorize_menu,
+    colorize_prompt,
+) -> None:
+    """Interactive ``nm`` submenu (multi-file dQ/dV only)."""
+    if not is_dqdv:
+        print("Normalize is only available in dQ/dV mode.")
+        print_menu(len(all_cycles), is_dqdv, fig, is_multi_file, menu_title, canvas_mode)
+        return
+    if not is_multi_file or not file_data or len(file_data) < 2:
+        print(
+            "Normalize is for multi-file dQ/dV overlays "
+            "(compare different instruments/files)."
+        )
+        print_menu(len(all_cycles), is_dqdv, fig, is_multi_file, menu_title, canvas_mode)
+        return
+
+    while True:
+        print("\n\033[1mdQ/dV normalize (per-file max |Y| → 1)\033[0m")
+        print(format_dqdv_norm_status(fig))
+        print("Works on plotted curves (Neware absolute / specific, BioLogic, …).")
+        print("Commands:")
+        print("  " + colorize_menu("a: normalize all visible files"))
+        print("  " + colorize_menu("f: normalize selected file number(s)"))
+        print("  " + colorize_menu("r: reset normalize (restore pre-norm Y)"))
+        print("  " + colorize_menu("q: back to main menu"))
+        sub = safe_input(colorize_prompt("Normalize command (a/f/r/q): ")).strip().lower()
+        if not sub:
+            continue
+        if sub == "q":
+            break
+        if sub == "r":
+            push_state("dqdv-norm-reset")
+            n = reset_dqdv_norm(
+                fig, file_data=file_data, cycle_lines=cycle_lines, ax=ax
+            )
+            if n:
+                print(f"Reset normalize on {n} curve(s).")
+            else:
+                print("No normalized curves to reset.")
+            continue
+        if sub in ("a", "all"):
+            push_state("dqdv-norm-apply")
+            cfg = apply_dqdv_norm(
+                fig,
+                file_data=file_data,
+                cycle_lines=cycle_lines,
+                file_indices=None,
+                visible_only=True,
+                ax=ax,
+            )
+            n_vis = sum(1 for f in file_data if f.get("visible", True))
+            print(f"Normalized {n_vis} visible file(s) ({cfg.get('method')}).")
+            continue
+        if sub == "f":
+            print_file_list(file_data, current_file_idx)
+            choice = safe_input(
+                f"File numbers (1-{len(file_data)}, space-separated) or q=cancel: "
+            ).strip().lower()
+            if not choice or choice == "q":
+                continue
+            try:
+                idxs = [int(x) - 1 for x in choice.replace(",", " ").split()]
+            except ValueError:
+                print("Invalid input.")
+                continue
+            if any(i < 0 or i >= len(file_data) for i in idxs):
+                print("Invalid file number.")
+                continue
+            push_state("dqdv-norm-apply")
+            cfg = apply_dqdv_norm(
+                fig,
+                file_data=file_data,
+                cycle_lines=cycle_lines,
+                file_indices=idxs,
+                visible_only=False,
+                ax=ax,
+            )
+            print(f"Normalized file(s) {[i + 1 for i in idxs]} ({cfg.get('method')}).")
+            continue
+        print("Unknown command.")
+
+    print_menu(len(all_cycles), is_dqdv, fig, is_multi_file, menu_title, canvas_mode)
+    print_file_list(file_data, current_file_idx)
+
+
+__all__ = [
+    "DEFAULT_METHOD",
+    "apply_dqdv_norm",
+    "clear_norm_attrs_on_cycle_lines",
+    "default_dqdv_norm_settings",
+    "format_dqdv_norm_status",
+    "get_dqdv_norm_settings",
+    "reapply_dqdv_norm_after_data_change",
+    "reset_dqdv_norm",
+    "run_dqdv_norm_menu",
+    "set_dqdv_norm_settings",
+]