Metadata-Version: 2.4
Name: batplot
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
        
        Copyright (c) 2025 Tian Dai
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/chem-plot/batplot
Project-URL: Repository, https://github.com/chem-plot/batplot
Project-URL: Issues, https://github.com/chem-plot/batplot/issues
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
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

# batplot

**Interactive plotting tool for battery and materials characterization data**

`batplot` is a Python CLI tool for visualizing and analyzing electrochemical and structural characterization data with interactive styling and session management. The electrochemistry and operando plots were inspired from Amalie Skurtveit's python scripts (https://github.com/piieceofcake?tab=repositories).

## Features

With a single line of command to easily plot publication-ready plots with customized, intuitive interactive editing features such as:
- **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

```bash
pip install batplot
# It is recommended to use separate environment for batplot to aviod compatability issues with dependencies.
```

## Quick Start

- Tutorial: https://drive.google.com/file/d/1NTFJWNBbWW4mgz0H5ZelGjuOBWxoFgkr/view
- Tutorial files: https://github.com/chem-plot/batplot/blob/main/batplot_tutorial.zip

---

## 1D (XY) Mode — XRD, PDF, XAS and much more

In batplot, --xaxis is frequently used to indicate the data type.

### Basic plotting

```bash

# 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
batplot pattern.xye --xaxis 2theta --xrange 10 80 --i

# Save to file (default .svg if no extension)
batplot pattern.xye --xaxis 2theta --out figure
batplot pattern.txt --xaxis Energy --out figure.png
```

### Strip header lines (export copies)

```bash
# 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
```

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

# 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

# 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
```

### Stacking and normalization

```bash
# Stack curves vertically (auto-normalizes)
batplot file1.xy file2.xy --stack --i

# Control spacing between stacked curves
batplot file1.xy file2.xy --stack --delta 0.15

# Normalize intensity to 0–1 (without stacking)
batplot file.xy --norm --i
```

### Dual y-axis (right y-axis)

```bash
# Plot selected files on the right y-axis (--ry disables --stack)
batplot file1.xy --ry file2.xy --ry file3.xy file4.xy --ry --i
# Files 1, 2, 4 use right y-axis; file 3 uses left y-axis

# With --txaxis: right y-axis curves use the top x-axis (default: shared bottom x)
batplot file1.xy --ry file2.xy --txaxis --i
```

### Column selection and multi-curve

```bash
# Read columns 2 and 3 as X, Y (1-indexed)
batplot data.xy --readcol 2 3 --wl 1.54 --i

# Per-file columns
batplot file1.xy --readcol 2 3 file2.xy --readcol 4 5 --xaxis r --i

# Multiple curves from same file (cols 1,2 and 1,3)
batplot data.xy --readcol 1 2 1 3 --xaxis 2theta --i

# Range: col 1 as x, cols 2–20 as 19 y-curves
batplot file.txt --readcol 1 2-20 --xaxis Energy --i

# With --convert: use custom columns when converting XRD data
batplot data.csv --readcol 3 4 --convert 1.54 q
```

### Derivatives and EXAFS

```bash
# Plot first derivative (dy/dx)
batplot file.xy --1d --stack --i

# EXAFS k-weighting
batplot data.chik --chik   --i        # χ(k)
batplot data.chik --k2chik        # k²χ(k), most common
batplot data.chik --k3chik --xrange 2 12
```

### Interactive menu

```bash
# Open interactive menu for styling, ranges, export, session save
batplot pattern.xye --i
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
# 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

### Data export requirements from instruments

- **Neware**: Customized report — check all boxes
- **Biologic**: Export all info to .mpt file

### Galvanostatic cycling (GC)

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

```

### Cyclic voltammetry (CV)

```bash
batplot cyclic.mpt --cv --i
```

### Differential capacity (dQ/dV)

```bash
batplot battery.csv --dqdv --i
```

### Capacity per cycle (CPC)

```bash
# Single file
batplot stability.csv --cpc --i
batplot stability.mpt --cpc --mass 5.4 --i

# Multiple files with individual colors
batplot file1.csv file2.mpt --cpc --mass 6.0 --i
```

### Time vs potential

```bash
# Plot time (h) vs potential from CSV/MPT
batplot battery.csv --xaxis time --i
```

### Potential window (custom potential–time .mpt)

```bash
# Two columns: potential, time. Use --pw and --cd to plot as GC
batplot custom.mpt --gc --pw 0.01 3 --cd 0.2 --i
```

---

## Operando Mode

Contour plots from a folder of diffraction data, optionally with an electrochemistry side panel.

### Bruker operando (.brml)

For Bruker operando XRD (multi-scan .brml files named cyc1, cyc2, cyc3, etc.):

```bash
# Place .brml files (e.g. RA_O5_cyc1.brml, RA_O5_cyc2.brml) in the folder
# Use --wl for Q conversion (e.g. synchrotron λ=0.709 Å)
batplot RA_O5 --operando --wl 0.709 --i

# EC side panel: .mpt or Biologic DataLogger CSV (*--DataLogger.csv), sorted by cyc
# Time vs potential is concatenated across files (continuous time axis)
```

### Standard XY files

```bash
# Contour from folder of .xy/.xye/.qye/.dat
batplot --operando --wl 1.54 --i

# With folder path
batplot /path/to/data --operando --xaxis 2theta --i

# Q conversion from 2θ
batplot --operando --wl 0.25995 --i

# Column selection: --readcolc for contour, --readcols for side panel (.mpt)
batplot --operando --readcolc 2 3 --readcols 1 2 --i

# Derivative contour
batplot --operando --1d --i

# With CIF tick labels
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)

---

## 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 --xaxis 2theta --i
batplot allfiles --stack --gc --i

# Only specific extension (natural-sorted)
batplot allxyfiles
batplot "/path/to/data" allnorfiles --xaxis energy --i

# Explicit file list
batplot file1.xye file2.qye structure.cif:1.54 --stack --i
```

---

## Batch export (--all)

Export each file as a separate figure to `Figures/`:

```bash
batplot --all
batplot --all --format png
batplot --all --xaxis 2theta --xrange 10 80
batplot --all style.bps --gc --mass 7

# With --readcol for custom columns (put --readcol before style file)
batplot --all --readcol 2 3 --xaxis 2theta
batplot --all --readcol 2 3 style.bps --xaxis 2theta
```

---

## Supported File Formats

| Type | Formats |
|------|---------|
| **Electrochemistry** | `.csv` (Neware, Biologic DataLogger), `.mpt` (Biologic), `.xlsx` (Landt/Lanhe CPC) |
| **XRD / PDF** | `.xye`, `.xy`, `.qye`, `.dat`, `.csv`, `.txt`; Bruker `.brml`, `.raw` |
| **Operando** | `.xy`, `.xye`, `.qye`, `.dat`; Bruker `.brml` (cyc1/cyc2/cyc3); EC: `.mpt` or DataLogger `.csv` |
| **XAS** | `.nor`, `.chik`, `.chir` |
| **Generic** | Use `--readcol` and `--xaxis` for custom formats |

---

## Interactive Features

With `--interactive`:
- **Cycle/Scan Control**: Toggle visibility, change colors
- **Multi-file palette (EC/CV/dQdV)**: Press `c`, then type `fall viridis` (all files), `f1-5 viridis` (files 1–5), or `f1 f3 f5 4` (each file gets one color)
- **CPC file palette**: In `ly`/`ry` color submenu, apply palette to file range: `1-5 viridis`, `1 3 5 4`
- **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

---

## Help & Documentation

```bash
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
```

---

## Requirements

- Python ≥ 3.9
- numpy
- matplotlib

## License

See [LICENSE](LICENSE)

## Author & Contact

Tian Dai  
tianda@uio.no  
University of Oslo  
https://www.mn.uio.no/kjemi/english/people/aca/tianda/  
https://github.com/chem-plot/

**Subscribe for Updates**: Join batplot-lab@kjemi.uio.no for updates. If not from UiO, email sympa@kjemi.uio.no with subject: "subscribe batplot-lab@kjemi.uio.no your-name"
