batplot 1.8.48__tar.gz → 1.8.51__tar.gz

{batplot-1.8.48 → batplot-1.8.51}/DEVELOPING.md

@@ -112,6 +112,9 @@ Important files:
 - `colors.py`, `line_style.py`, `labels.py`, `axis_range.py`, `smoothing.py`,
   `derivative.py`, `peaks.py`, `cif.py`, `data_ops.py`, `arrange.py`: focused
   XY features.
+- `undo_state.py`: undo snapshot capture/restore (`xy_push_state` /
+  `xy_restore_state`), called through thin wrappers in `interactive.py`.
+- `offset_menu.py`: the `o` curve-offset submenu.
 
 ### Electrochemistry Mode
 
@@ -125,6 +128,10 @@ Important files:
 - `dqdv_2d.py`: dQ/dV 2D companion contour persistence and helpers.
 - `style.py`, `colors.py`, `line_style.py`, `labels.py`, `legend.py`,
   `legend_order.py`, `spine_colors.py`: EC styling features.
+- `undo_state.py`: undo snapshot capture/restore (`ec_push_state` /
+  `ec_restore_state`), called through thin wrappers in `interactive.py`.
+- `dual_axis_menu.py`: the `a` capacity/ions/dual-X submenu.
+- `smoothing_menu.py`: the `sm` dQ/dV smoothing submenu.
 
 Shared EC/CPC defaults live in `batplot/ec_common.py`. Canvas size, plot layout,
 and mass-resolution behavior should be changed there when the goal is parity
@@ -141,6 +148,9 @@ Important files:
 - `interactive.py`: CPC-specific interactive command loop.
 - `actions.py`: save/export/undo actions.
 - `legend.py`, `colors.py`, `labels.py`, `snapshots.py`: CPC-specific behavior.
+- `wasd_menu.py`: the `t` WASD spine/tick/label toggle submenu.
+- `panel_menus.py`: the `v`/`k`/`d`/`ry`/`l`/`m`/`ie` submenus (visibility,
+  spine colors, display mode, efficiency axis, widths, markers, inversion).
 - `session.py`: public CPC session wrappers.
 
 CPC shares several expectations with EC but has a second y-axis and scatter
@@ -162,6 +172,12 @@ Important files:
   display behavior.
 - `style.py`, `colors.py`, `labels.py`, `line_style.py`, `peaks.py`: styling
   and annotation behavior.
+- `undo_state.py`: undo snapshot capture/restore (`op_snapshot` /
+  `op_restore`), called through thin wrappers in `interactive.py`.
+- `cif_menu.py`: the `c` CIF tick-label submenu.
+- `axes_limits_menu.py`: the `ox`/`oy`/`et`/`ex`/`ey` range and ions/time
+  submenus.
+- `intensity_menu.py`: the `oz` color-scale submenu (including the drag bar).
 - `session.py`: public operando session wrappers.
 
 Operando state has more moving parts than the other modes. Keep changes focused
@@ -171,7 +187,15 @@ and add round-trip tests for persistence changes.
 
 ### Readers
 
-File parsing lives primarily in `batplot/readers.py`.
+File parsing lives primarily in `batplot/readers.py`, which re-exports every
+public reader so `from batplot.readers import ...` always works. The
+implementations are split by area:
+
+- `readers.py`: generic CSV/XY readers plus the re-export facade.
+- `readers_ec.py`: electrochemistry readers (BioLogic, Neware, Landt, CS-B,
+  BATX, dQ/dV numerics, time-voltage).
+- `readers_xrd.py`: XRD vendor formats.
+- `readers_common.py`: low-level numeric parsing helpers shared by the above.
 
 Add a reader here when:
 

{batplot-1.8.48 → batplot-1.8.51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batplot
-Version: 1.8.48
+Version: 1.8.51
 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
@@ -45,10 +45,12 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: numpy>=1.21.0
 Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: scipy>=1.7.0
 Requires-Dist: rich>=10.0.0
 Requires-Dist: openpyxl>=3.0.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-timeout>=2.0; extra == "test"
 Requires-Dist: basedpyright>=1.28.0; extra == "test"
 Dynamic: license-file
 
@@ -64,12 +66,14 @@ 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
+- **XRD axis units**: Interactive Options `u` converts 2θ ↔ Q ↔ d (XY and operando); CIF phase ticks follow the current domain
 - **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 (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.)
+- **Strip header lines**: `--strip-header N` removes the first N lines from a file or a folder of files (with `--ext`) and writes copies into a `stripped/` subfolder (originals untouched)
 
 ## Installation
 
@@ -82,7 +86,6 @@ pip install batplot
 
 - Tutorial: https://drive.google.com/file/d/1NTFJWNBbWW4mgz0H5ZelGjuOBWxoFgkr/view
 - Tutorial files: https://github.com/chem-plot/batplot/blob/main/batplot_tutorial.zip
-- Manual: https://github.com/chem-plot/batplot/blob/main/batplot_user_manual.pdf
 
 ---
 
@@ -94,11 +97,12 @@ In batplot, --xaxis is frequently used to indicate the data type.
 
 ```bash
 
-# Specify X-axis type (Q, 2theta, r, k, energy, time or any user defined names)
+# Specify X-axis type (Q, 2theta, d, r, k, energy, time or any user defined names)
 # By defauly, batplot will skip the header lines, plot the first and second columns as x and y
 # Q and q are equivalent (case-insensitive)
 batplot pattern.xye --xaxis 2theta --i
 batplot data.qye --xaxis q --i
+batplot data.xye --xaxis d --wl 1.54 --i
 batplot data.txt --xaxis whatever --i
 
 # Set X-axis range
@@ -109,20 +113,41 @@ batplot pattern.xye --xaxis 2theta --out figure
 batplot pattern.txt --xaxis Energy --out figure.png
 ```
 
-### Wavelength and Q conversion for XRD data
+### Strip header lines (export copies)
 
 ```bash
-# Convert 2θ to Q using wavelength (Å), --xaxis is no longer needed as providing wavelength is implying that user wants to convert and plot the data in Q space
-batplot data.raw --wl 1.5406 --i
+# Single file: drop first 5 lines → ./stripped/data.txt
+batplot data.txt --strip-header 5
+
+# Folder: only .xy files → folder/stripped/*.xy
+batplot /path/to/folder --strip-header 3 --ext .xy
+
+# Multiple extensions (comma-separated)
+batplot /path/to/folder --strip-header 2 --ext .xy,.dat,.txt
+```
 
-# Per-file wavelength: file.xye:1.54, in this case --xaxis is also not needed and files will be plotted in Q space
+Originals are never modified. Binary formats (`.brml`, `.raw`, `.xlsx`, …) are skipped.
+
+### Wavelength and XRD unit conversion (plot vs export)
+
+```bash
+# Plot: convert 2θ→Q for display (λ in Å). --xaxis not needed when --wl / file:λ is given
+batplot data.raw --wl 1.5406 --i
 batplot scan1.brml:1.5406 scan2.xye:0.7093 --i
 
-# Convert and export to converted/ subfolder (q and Q equivalent)
-batplot data.xye --convert 1.54 q
-batplot data.qye --convert q 1.54
+# Export: --convert writes into a converted/ subfolder next to each input
+# Units: q|Q, d|D, 2theta|2th|tth  — or a number = 2θ at that wavelength
+batplot data.xye --convert 1.54 q          # 2θ(λ=1.54) → Q  → *.qye
+batplot data.qye --convert q 1.54          # Q → 2θ(λ=1.54) → *.xy
+batplot data.qye --convert q d             # Q ↔ d (no λ)
+batplot data.xy --convert d 2theta --wl 1.5406
+batplot data.xye --convert 0.26 1.54       # 2θ(λ1) → 2θ(λ2)
+
+# Folder of .xy → Q with typed extension filter / output extension
+batplot /path/to/folder --ext .xy --convert 0.26 q
+batplot /path/to/folder --ext xy --convert 2theta q --wl 0.26 --convert-ext .qye
 
-# With --readcol for custom column layout (e.g. 2θ in col 3, intensity in col 4)
+# Custom columns when converting
 batplot data.csv --readcol 3 4 --convert 1.54 q
 batplot f1.txt --readcol 2 3 f2.txt --readcol 5 6 --convert 1.54 q
 ```
@@ -191,6 +216,27 @@ batplot file1.xy file2.xy --stack --i
 batplot allfiles --xaxis 2theta --xrange 15 75 --i
 ```
 
+**XRD Options `u` (axis units):** On diffraction plots only, press `u` to convert the x-axis among **2θ ↔ Q ↔ d**. Conversions that involve 2θ need a wavelength (`--wl`, `file:wl`, or a prompt). Data, axis labels/limits, and CIF ticks stay in sync. Not available for PDF/XAS or other non-XRD axes.
+
+```bash
+# Launch in 2θ, then use Options u → q (or d) inside the menu
+batplot data.xye:0.709 --xaxis 2theta --i
+batplot data.xye --xaxis 2theta --wl 1.5406 --i
+```
+
+### CIF phase ticks
+
+Add one or more `.cif` files to overlay Bragg reflection markers. Peaks are stored in Q and drawn in the current axis domain (2θ / Q / d). Use `cif` in the interactive menu to add, rename, or hide sets; after Options `u`, ticks redraw in the new units.
+
+```bash
+# Q plot + CIF ticks
+batplot scan.xye:1.54 phase.cif --i
+
+# 2θ plot: give λ for data and/or CIF (file.cif:wl)
+batplot scan.xye phase.cif:0.709 --xaxis 2theta --wl 0.709 --i
+batplot scan.xye:1.54 phase.cif --stack --i
+```
+
 ### Session save without interactive menu (`--save`)
 
 ```bash
@@ -219,10 +265,16 @@ batplot file1.csv file2.csv --gc --save
 
 GC mode plots potential vs. capacity for each charge/discharge cycle—the primary visualization for battery cycling data. Batplot automatically detects cycles from Neware `.csv` or Biologic `.mpt` files, assigns each cycle a distinct color, and supports both specific capacity (mAh/g) and raw capacity. For `.mpt` files, pass `--mass` (mg) to compute specific capacity. Discontinuous or paused experiments are handled by splitting data into contiguous charge/discharge segments. Use the interactive menu to customize colors, visibility, and export.
 
+By default each half-cycle resets capacity near 0 (cycles overlaid). With `--gc --cum`, capacity is laid **end-to-end** (cumulative / throughput capacity) so charge and discharge connect from the start to the end of the experiment; cycle colors, multifile overlay, overview, display mode, style/session save, and `--ro` still apply.
+
 ```bash
 # From .csv (capacity in file)
 batplot battery.csv --gc --i
 
+# Cumulative capacity (charge/discharge connected end-to-end)
+batplot battery.csv --gc --cum --i
+batplot f1.csv f2.csv --gc --cum --i
+
 # From .mpt (requires --mass in mg)
 batplot battery.mpt --gc --mass 7.0 --i
 
@@ -306,6 +358,12 @@ batplot --operando --1d --i
 batplot folder phase.cif:1.54 --operando --i
 ```
 
+**XRD Options `u`:** In the operando interactive menu, press `u` to convert the contour x-axis among **2θ ↔ Q ↔ d** (XRD only; needs λ for 2θ). CIF ticks follow the new domain. Prefer an explicit `--xaxis` when combining with `--wl` (e.g. `--xaxis 2theta --wl 0.709` keeps degrees; `--wl` alone still defaults to Q).
+
+```bash
+batplot folder phase.cif --operando --xaxis 2theta --wl 0.709 --i
+```
+
 Operando column selection:
 - `--readcolc <x> <y>`: columns for the contour plot (from .xy/.xye/.qye/.dat files)
 - `--readcols <x> <y>`: columns for the side panel (from .mpt file)

{batplot-1.8.48 → batplot-1.8.51}/README.md

@@ -10,12 +10,14 @@ 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
+- **XRD axis units**: Interactive Options `u` converts 2θ ↔ Q ↔ d (XY and operando); CIF phase ticks follow the current domain
 - **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 (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.)
+- **Strip header lines**: `--strip-header N` removes the first N lines from a file or a folder of files (with `--ext`) and writes copies into a `stripped/` subfolder (originals untouched)
 
 ## Installation
 
@@ -28,7 +30,6 @@ pip install batplot
 
 - Tutorial: https://drive.google.com/file/d/1NTFJWNBbWW4mgz0H5ZelGjuOBWxoFgkr/view
 - Tutorial files: https://github.com/chem-plot/batplot/blob/main/batplot_tutorial.zip
-- Manual: https://github.com/chem-plot/batplot/blob/main/batplot_user_manual.pdf
 
 ---
 
@@ -40,11 +41,12 @@ In batplot, --xaxis is frequently used to indicate the data type.
 
 ```bash
 
-# Specify X-axis type (Q, 2theta, r, k, energy, time or any user defined names)
+# Specify X-axis type (Q, 2theta, d, r, k, energy, time or any user defined names)
 # By defauly, batplot will skip the header lines, plot the first and second columns as x and y
 # Q and q are equivalent (case-insensitive)
 batplot pattern.xye --xaxis 2theta --i
 batplot data.qye --xaxis q --i
+batplot data.xye --xaxis d --wl 1.54 --i
 batplot data.txt --xaxis whatever --i
 
 # Set X-axis range
@@ -55,20 +57,41 @@ batplot pattern.xye --xaxis 2theta --out figure
 batplot pattern.txt --xaxis Energy --out figure.png
 ```
 
-### Wavelength and Q conversion for XRD data
+### Strip header lines (export copies)
 
 ```bash
-# Convert 2θ to Q using wavelength (Å), --xaxis is no longer needed as providing wavelength is implying that user wants to convert and plot the data in Q space
-batplot data.raw --wl 1.5406 --i
+# Single file: drop first 5 lines → ./stripped/data.txt
+batplot data.txt --strip-header 5
+
+# Folder: only .xy files → folder/stripped/*.xy
+batplot /path/to/folder --strip-header 3 --ext .xy
+
+# Multiple extensions (comma-separated)
+batplot /path/to/folder --strip-header 2 --ext .xy,.dat,.txt
+```
 
-# Per-file wavelength: file.xye:1.54, in this case --xaxis is also not needed and files will be plotted in Q space
+Originals are never modified. Binary formats (`.brml`, `.raw`, `.xlsx`, …) are skipped.
+
+### Wavelength and XRD unit conversion (plot vs export)
+
+```bash
+# Plot: convert 2θ→Q for display (λ in Å). --xaxis not needed when --wl / file:λ is given
+batplot data.raw --wl 1.5406 --i
 batplot scan1.brml:1.5406 scan2.xye:0.7093 --i
 
-# Convert and export to converted/ subfolder (q and Q equivalent)
-batplot data.xye --convert 1.54 q
-batplot data.qye --convert q 1.54
+# Export: --convert writes into a converted/ subfolder next to each input
+# Units: q|Q, d|D, 2theta|2th|tth  — or a number = 2θ at that wavelength
+batplot data.xye --convert 1.54 q          # 2θ(λ=1.54) → Q  → *.qye
+batplot data.qye --convert q 1.54          # Q → 2θ(λ=1.54) → *.xy
+batplot data.qye --convert q d             # Q ↔ d (no λ)
+batplot data.xy --convert d 2theta --wl 1.5406
+batplot data.xye --convert 0.26 1.54       # 2θ(λ1) → 2θ(λ2)
+
+# Folder of .xy → Q with typed extension filter / output extension
+batplot /path/to/folder --ext .xy --convert 0.26 q
+batplot /path/to/folder --ext xy --convert 2theta q --wl 0.26 --convert-ext .qye
 
-# With --readcol for custom column layout (e.g. 2θ in col 3, intensity in col 4)
+# Custom columns when converting
 batplot data.csv --readcol 3 4 --convert 1.54 q
 batplot f1.txt --readcol 2 3 f2.txt --readcol 5 6 --convert 1.54 q
 ```
@@ -137,6 +160,27 @@ batplot file1.xy file2.xy --stack --i
 batplot allfiles --xaxis 2theta --xrange 15 75 --i
 ```
 
+**XRD Options `u` (axis units):** On diffraction plots only, press `u` to convert the x-axis among **2θ ↔ Q ↔ d**. Conversions that involve 2θ need a wavelength (`--wl`, `file:wl`, or a prompt). Data, axis labels/limits, and CIF ticks stay in sync. Not available for PDF/XAS or other non-XRD axes.
+
+```bash
+# Launch in 2θ, then use Options u → q (or d) inside the menu
+batplot data.xye:0.709 --xaxis 2theta --i
+batplot data.xye --xaxis 2theta --wl 1.5406 --i
+```
+
+### CIF phase ticks
+
+Add one or more `.cif` files to overlay Bragg reflection markers. Peaks are stored in Q and drawn in the current axis domain (2θ / Q / d). Use `cif` in the interactive menu to add, rename, or hide sets; after Options `u`, ticks redraw in the new units.
+
+```bash
+# Q plot + CIF ticks
+batplot scan.xye:1.54 phase.cif --i
+
+# 2θ plot: give λ for data and/or CIF (file.cif:wl)
+batplot scan.xye phase.cif:0.709 --xaxis 2theta --wl 0.709 --i
+batplot scan.xye:1.54 phase.cif --stack --i
+```
+
 ### Session save without interactive menu (`--save`)
 
 ```bash
@@ -165,10 +209,16 @@ batplot file1.csv file2.csv --gc --save
 
 GC mode plots potential vs. capacity for each charge/discharge cycle—the primary visualization for battery cycling data. Batplot automatically detects cycles from Neware `.csv` or Biologic `.mpt` files, assigns each cycle a distinct color, and supports both specific capacity (mAh/g) and raw capacity. For `.mpt` files, pass `--mass` (mg) to compute specific capacity. Discontinuous or paused experiments are handled by splitting data into contiguous charge/discharge segments. Use the interactive menu to customize colors, visibility, and export.
 
+By default each half-cycle resets capacity near 0 (cycles overlaid). With `--gc --cum`, capacity is laid **end-to-end** (cumulative / throughput capacity) so charge and discharge connect from the start to the end of the experiment; cycle colors, multifile overlay, overview, display mode, style/session save, and `--ro` still apply.
+
 ```bash
 # From .csv (capacity in file)
 batplot battery.csv --gc --i
 
+# Cumulative capacity (charge/discharge connected end-to-end)
+batplot battery.csv --gc --cum --i
+batplot f1.csv f2.csv --gc --cum --i
+
 # From .mpt (requires --mass in mg)
 batplot battery.mpt --gc --mass 7.0 --i
 
@@ -252,6 +302,12 @@ batplot --operando --1d --i
 batplot folder phase.cif:1.54 --operando --i
 ```
 
+**XRD Options `u`:** In the operando interactive menu, press `u` to convert the contour x-axis among **2θ ↔ Q ↔ d** (XRD only; needs λ for 2θ). CIF ticks follow the new domain. Prefer an explicit `--xaxis` when combining with `--wl` (e.g. `--xaxis 2theta --wl 0.709` keeps degrees; `--wl` alone still defaults to Q).
+
+```bash
+batplot folder phase.cif --operando --xaxis 2theta --wl 0.709 --i
+```
+
 Operando column selection:
 - `--readcolc <x> <y>`: columns for the contour plot (from .xy/.xye/.qye/.dat files)
 - `--readcols <x> <y>`: columns for the side panel (from .mpt file)

{batplot-1.8.48 → batplot-1.8.51}/batplot/__init__.py

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

{batplot-1.8.48 → batplot-1.8.51}/batplot/args.py

@@ -158,6 +158,7 @@ def _print_general_help() -> None:
         "  [Electrochemistry]\n"
         "    batplot --gc file.mpt --mass 7.0 --i       # GC from .mpt\n"
         "    batplot --gc file.csv --i                 # GC from .csv\n"
+        "    batplot --gc --cum file.csv --i           # GC cumulative capacity (end-to-end)\n"
         "    batplot --dqdv file.csv --i               # dQ/dV\n"
         "    batplot --cv file.mpt --i                 # Cyclic voltammetry\n"
         "    batplot --cpc file.csv --mass 3.52 --i     # Capacity per cycle\n\n"
@@ -172,6 +173,8 @@ def _print_general_help() -> None:
         "Features:\n"
         "  • Interactive (--i): styling, ranges, fonts, export, sessions\n"
         "  • XRD wavelength: --wl 1.54 or file.xye:1.5406 for Q conversion\n"
+        "  • XRD axis units (interactive): Options u converts 2θ ↔ Q ↔ d (XY + operando; needs λ for 2θ)\n"
+        "  • CIF phase ticks: add .cif (or file.cif:wl); ticks follow the current axis (2θ / Q / d)\n"
         "  • X-axis range: --xrange min max\n"
         "  • Save figure: --out filename (default .svg)\n"
         "  • Save session: --save (choose folder + name; default stem for single file / --all batch)\n"
@@ -181,6 +184,8 @@ def _print_general_help() -> None:
         "More help:\n"
         "  batplot --v       # Version and release info (with option to show full release notes)\n"
         "  batplot --showcol FILE [FILE...]   # Preview column names + first 10 values per column\n"
+        "  batplot FILE --strip-header N       # Remove first N lines; write to stripped/ subfolder\n"
+        "  batplot FOLDER --strip-header N --ext .xy   # Same for a folder (comma-separated exts ok)\n"
         "  batplot --h          # This help\n"
         "  batplot --h xy       # XY file plotting guide\n"
         "  batplot --h ec       # Electrochemistry (GC/dQdV/CV/CPC) guide\n"
@@ -204,10 +209,21 @@ def _print_xy_help() -> None:
     msg = (
         "XY plots (XRD/PDF/XAS and many more)\n\n"
         "Supported files: .xye .xy .qye .dat .csv .gr .nor .chik .chir .txt .brml .raw .xrdml .rasx and other formats. CIF overlays supported.\n\n"
-        "Axis detection: .qye→Q, .gr→r, .nor→energy, .chik→k, .chir→r, else use --xaxis (Q, 2theta, r, k, energy, time or user defined).\n"
+        "Axis detection: .qye→Q, .gr→r, .nor→energy, .chik→k, .chir→r, else use --xaxis (Q, 2theta, d, r, k, energy, time or user defined).\n"
         "If mixing 2θ data in Q, give wavelength per-file (file.xye:1.5406) or global flag --wl.\n"
         "A wavelength can be converted into a different wave length by file.xye:1.54:0.709.\n"
         "For electrochemistry CSV/MPT time-potential plots, use --xaxis time.\n\n"
+        "Interactive XRD axis units (Options u):\n"
+        "  In --i, press u to convert the plotted XRD axis among 2θ ↔ Q ↔ d (XRD data only).\n"
+        "  Conversions involving 2θ need λ (--wl, file:wl, or prompt). CIF ticks stay Bragg-aligned.\n"
+        "  Not for PDF (.gr), XAS (.nor/.chik/.chir), or other non-diffraction axes.\n"
+        "  Example: batplot data.xye:0.709 --xaxis 2theta --i   then u → q  (uses λ=0.709 Å).\n\n"
+        "CIF phase ticks:\n"
+        "  Add .cif files on the command line (optional :wl for 2θ). Peaks are stored in Q and\n"
+        "  drawn in the current domain (2θ / Q / d). In --i use cif to add/reorder/hide ticks;\n"
+        "  after Options u, ticks redraw in the new units. Example:\n"
+        "    batplot scan.xye:1.54 phase.cif --i\n"
+        "    batplot scan.xye phase.cif:0.709 --xaxis 2theta --wl 0.709 --i\n\n"
         "Examples:\n"
         "  batplot file.xy file2.xye --xaxis 2theta --i         # Plot XRD data in 2theta space\n"
         "  batplot file1.xye:1.5406 file2.txt:0.709 --i         # Plot XRD data in different wavelengths in q space\n"
@@ -225,6 +241,7 @@ def _print_xy_help() -> None:
         "Tips and options:\n"
         "[XY plot]\n"
         "  --i            : open interactive menu for styling, ranges, fonts, export, sessions\n"
+        "                   (XRD: Options u = convert axis 2θ ↔ Q ↔ d; cif = phase tick overlay)\n"
         "  --delta <float>           : spacing between curves, e.g. --delta 0.1\n"
         "  --norm                    : normalize intensity to 0-1 range. Stack mode (--stack) auto-normalizes\n"
         "  --chik                    : EXAFS χ(k) plot (sets labels to k (Å⁻¹) vs χ(k))\n"
@@ -236,26 +253,38 @@ def _print_xy_help() -> None:
         "  --xrange <min> <max>      : set x-axis range, e.g. --xrange 0 10\n"
         "  --out <filename>          : save figure to file, e.g. --out file.svg\n"
         "  --save                    : save .pkl session (prompt folder + name; no --i menu)\n"
-        "  --xaxis <type>            : set x-axis type (Q, 2theta, r, k, energy, rft, time, or user defined)\n"
-        "                              Q and q are equivalent (case-insensitive). e.g. --xaxis 2theta, --xaxis Q, --xaxis time\n"
+        "  --xaxis <type>            : set x-axis type (Q, 2theta, d, r, k, energy, rft, time, or user defined)\n"
+        "                              Q and q are equivalent (case-insensitive). e.g. --xaxis 2theta, --xaxis Q, --xaxis d\n"
         "  --ro                      : swap x and y axes (exchange x and y values before plotting)\n"
         "                              e.g. --xaxis time --ro plots time as y-axis and potential as x-axis\n"
         "  --wl <float>              : set wavelength for Q conversion for all files, e.g. --wl 1.5406\n"
-        "  --convert <from> <to>     : convert XRD data and export to 'converted' subfolder:\n"
-        "                              - <wl1> <wl2>  : convert 2θ from wavelength1 to wavelength2\n"
-        "                              - <wl> q or Q  : convert 2θ (with wavelength) to Q space (q and Q equivalent)\n"
-        "                              - q or Q <wl>  : convert Q space to 2θ (with wavelength)\n"
-        "                              Works with --readcol for custom column layout (per-file, per-ext, or global):\n"
+        "  --strip-header <N>        : remove the first N lines from text file(s) and export copies\n"
+        "                              into a 'stripped/' subfolder next to each input (originals untouched).\n"
+        "                              Single file:  batplot data.txt --strip-header 5\n"
+        "                              Folder:       batplot /path/to/folder --strip-header 3 --ext .xy\n"
+        "                              Multiple exts: batplot folder --strip-header 2 --ext .xy,.dat,.txt\n"
+        "                              (--ext required for folders; optional filter when listing files)\n"
+        "  --convert <from> <to>     : convert XRD x-axis and export to a 'converted/' subfolder:\n"
+        "                              Units: q|Q, d|D, 2theta|2th|tth  (or a numeric wavelength = 2θ at that λ)\n"
+        "                              - <wl1> <wl2>     : 2θ(λ1) → 2θ(λ2)\n"
+        "                              - <wl> q          : 2θ(λ) → Q\n"
+        "                              - q <wl>          : Q → 2θ(λ)\n"
+        "                              - q d / d q       : Q ↔ d (no λ needed)\n"
+        "                              - <wl> d / d <wl> : 2θ(λ) ↔ d\n"
+        "                              - 2theta q --wl λ : same as `<wl> q` (explicit unit names)\n"
+        "                              Folder of .xy → Q (writes folder/converted/*.qye):\n"
+        "                                batplot /path/to/folder --ext .xy --convert 0.26 q\n"
+        "                              Choose input / output extensions:\n"
+        "                                --ext .xy            : only convert this extension in a folder\n"
+        "                                --convert-ext .qye   : force output extension (default: .qye for Q, .xy otherwise)\n"
+        "                              With --readcol:\n"
         "                                batplot data.csv --readcol 3 4 --convert 1.54 q\n"
-        "                                batplot f1.txt --readcol 2 3 f2.txt --readcol 5 6 --convert 1.54 q\n"
-        "                              Directory: pass a folder to convert all .xy/.xye/.qye/.dat/.csv/.txt files:\n"
-        "                                batplot /path/to/folder --convert 0.25448 1.54\n"
-        "                              Batch in current folder: use allfiles token (non-convertible files are skipped):\n"
-        "                                batplot allfiles --convert q 1.54\n"
         "                              Examples:\n"
         "                                batplot file.xye --convert 1.54 0.25\n"
         "                                batplot file.xye --convert 1.54 q\n"
+        "                                batplot file.qye --convert q d\n"
         "                                batplot file.qye --convert Q 1.54\n"
+        "                                batplot allfiles --ext xy --convert 2theta q --wl 1.5406 --convert-ext qye\n"
         "  File wavelength syntax   : specify wavelength(s) per file using colon syntax:\n"
         "                              - file:wl          : single wavelength (for Q conversion or CIF 2theta calculation)\n"
         "                              - file:wl1:wl2     : dual wavelength (convert 2theta→Q using wl1, then Q→2theta using wl2)\n"
@@ -305,6 +334,7 @@ def _print_ec_help() -> None:
         "GC from supported .csv: specific capacity read directly when available; use --mass for\n"
         "  Neware absolute-capacity files (Cycle Index / Step Index / DataPoint format).\n"
         "  batplot --gc file.csv\n"
+        "  batplot --gc --cum file.csv --i        # Cumulative capacity (charge/discharge end-to-end)\n"
         "  batplot --gc file.csv --mass 3.52       # Neware absolute-capacity CSV\n\n"
         "Per-file mass: repeat --mass once per file that needs it, in file order.\n"
         "  batplot f1.mpt --mass 6.5 f2.csv f3.mpt --mass 7.0 --gc\n"
@@ -426,6 +456,9 @@ def _print_op_help() -> None:
         "Interactive (--i): menu has (Styles), (Operando), (Side Panel), (Options) columns.\n"
         "Resize axes/canvas, change colormap, set intensity range (oz), side-panel options,\n"
         "geometry tweaks, toggle spines/ticks/labels, print/export/import style, save session.\n"
+        "XRD only — Options u: convert contour X among 2θ ↔ Q ↔ d (needs λ for 2θ; CIF ticks follow).\n"
+        "CIF: add .cif on the command line or via the CIF submenu; ticks stay Bragg-aligned after u.\n"
+        "  Example: batplot folder phase.cif --operando --xaxis 2theta --wl 0.709 --i\n"
         "Session save without menu: --save (combined operando plot — session name required).\n"
     )
     _print_help(msg)
@@ -442,6 +475,14 @@ def _add_help_and_entry_arguments(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help=argparse.SUPPRESS,
     )
+    parser.add_argument(
+        "--strip-header",
+        type=int,
+        metavar="N",
+        dest="strip_header",
+        default=None,
+        help=argparse.SUPPRESS,
+    )
     parser.add_argument("--manual", action="store_true", help=argparse.SUPPRESS)
     parser.add_argument("files", nargs="*", help=argparse.SUPPRESS)
 
@@ -455,7 +496,26 @@ def _add_xy_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--errors", action="store_true", help=argparse.SUPPRESS)
     parser.add_argument("--xaxis", type=str, help=argparse.SUPPRESS)
     parser.add_argument("--convert", nargs=2, metavar=("FROM", "TO"), 
-                        help="Convert XRD data: wavelength-to-wavelength (e.g., 1.54 0.25), wavelength-to-Q (e.g., 1.54 q), or Q-to-wavelength (e.g., q 1.54). Exports to 'converted' subfolder.")
+                        help="Convert XRD data among 2θ/Q/d (or λ1→λ2 for 2θ). Exports to 'converted' subfolder.")
+    parser.add_argument(
+        "--ext",
+        type=str,
+        default=None,
+        metavar="EXT",
+        help=(
+            "With --convert or --strip-header: only process files with this extension "
+            "(e.g. .xy or xy). For --strip-header, comma-separated lists are allowed "
+            "(e.g. .xy,.dat,.txt)."
+        ),
+    )
+    parser.add_argument(
+        "--convert-ext",
+        type=str,
+        default=None,
+        metavar="EXT",
+        dest="convert_ext",
+        help="With --convert: output file extension (e.g. .qye or qye). Default: .qye for Q, .xy otherwise.",
+    )
     parser.add_argument("--extract-brml-scans", nargs="?", const="", metavar="OUT_DIR",
                         help="Extract each XRD scan from .brml file to separate .xy files. Optional OUT_DIR (default: <brml_stem>_scans).")
     parser.add_argument("--wl", type=float, help=argparse.SUPPRESS)
@@ -495,6 +555,11 @@ def _add_interactive_export_arguments(parser: argparse.ArgumentParser) -> None:
 def _add_electrochem_arguments(parser: argparse.ArgumentParser) -> None:
     """Register electrochemistry mode arguments."""
     parser.add_argument("--gc", action="store_true", help=argparse.SUPPRESS)
+    parser.add_argument(
+        "--cum",
+        action="store_true",
+        help="With --gc: plot cumulative (throughput) capacity — charge/discharge laid end-to-end.",
+    )
     parser.add_argument("--mass", type=parse_mass_mg_from_cli, action='append', help=argparse.SUPPRESS)
     parser.add_argument("--dqdv", action="store_true", help=argparse.SUPPRESS)
     parser.add_argument("--cv", action="store_true", help=argparse.SUPPRESS)

{batplot-1.8.48 → batplot-1.8.51}/batplot/batch.py

@@ -40,6 +40,7 @@ def _is_mpt_like_ext(ext: str) -> bool:
 
 
 from .ec_common import _resolve_mass
+from .plot_modes.electrochem.capacity_cum import apply_gc_capacity_mode, stamp_gc_capacity_mode
 from .utils import _confirm_overwrite, natural_sort_key, ensure_subdirectory
 
 
@@ -255,6 +256,7 @@ def batch_process(directory: str, args):
             # We detect the format from the file extension and use the
             # appropriate reader function.
             # ============================================================
+            file_wl = getattr(args, "wl", None)
             
             if ext == '.gr':
                 x, y = read_gr_file(fpath); e = None
@@ -281,8 +283,9 @@ def batch_process(directory: str, args):
             elif ext in ('.brml', '.xrdml', '.rasx') or (ext == '.raw' and is_bruker_raw(fpath)):
                 x, y, e, wl_from_file = read_xrd_vendor_file(fpath)
                 axis_mode = '2theta'
-                if args.wl is None and wl_from_file is not None:
-                    args.wl = wl_from_file
+                if file_wl is None and wl_from_file is not None:
+                    # Per-file wavelength only — do not mutate shared args.wl
+                    file_wl = wl_from_file
             elif ext == '.raw':
                 # .raw from non-Bruker instrument: load as generic text
                 data = robust_loadtxt_skipheader(fpath)
@@ -374,12 +377,12 @@ def batch_process(directory: str, args):
 
             # Convert to Q if needed
             if axis_mode == 'Q' and ext not in ('.qye', '.gr', '.nor'):
-                if args.wl is None:
+                if file_wl is None:
                     axis_mode = '2theta'
                     x_plot = x
                 else:
                     theta_rad = np.radians(x/2)
-                    x_plot = 4*np.pi*np.sin(theta_rad)/args.wl
+                    x_plot = 4*np.pi*np.sin(theta_rad)/file_wl
             else:
                 x_plot = x
 
@@ -704,6 +707,10 @@ def batch_process_ec(directory: str, args):
                     x_label = r'Specific Capacity (mAh g$^{-1}$)'
                 else:
                     raise ValueError(f"Unsupported file type for GC: {ext}")
+
+                cap_x, x_label, _cum_gc = apply_gc_capacity_mode(
+                    args, cap_x, charge_mask, discharge_mask, x_label
+                )
                 
                 # Plot cycles
                 if cycle_numbers is not None:
@@ -756,6 +763,7 @@ def batch_process_ec(directory: str, args):
                 ax_b.set_title(f"{fname}")
                 legend = ax_b.legend(loc='best', fontsize='small', framealpha=0.8, title='Cycle')
                 sync_legend_title_fontsize(legend)
+                stamp_gc_capacity_mode(fig_b, cumulative=_cum_gc)
             
             # ---- CV Mode ----
             elif mode == 'cv':