Metadata-Version: 2.4
Name: pyflowbatt
Version: 0.3.0rc2
Summary: Tools for analysing data from the flow battery lab at Empa
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: batterydf>=0.1.0,<0.2.0
Requires-Dist: battinfoconverter-backend>=3.4.0,<4.0.0
Requires-Dist: fasteis==0.1.0
Requires-Dist: matplotlib>=3.10.6
Requires-Dist: pandas>=2.3.2
Requires-Dist: pyarrow>=21.0.0
Requires-Dist: xlsxwriter>=3.2.9
Requires-Dist: rocrate>=0.9
Requires-Dist: yadg>=7.0.1,<8.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: rich>=13.0.0

# 🌊 PyFlowBatt

This Python package contains functions and a CLI for analysing data from the flow battery lab at Empa.


## Installation

Use Python >=3.10, and install with pip:
```
pip install pyflowbatt
```

## Usage

Use in a terminal (e.g. Command Prompt or PowerShell).

To analyse the data in a folder, use
```
pyflowbatt --folder "path/to/your/folder"
```
Or go to a folder and just run `pyflowbatt`:
```
cd path/to/your/folder
pyflowbatt
```

PyFlowBatt processes the data, converts it to battery data format, makes summary graphs and Excel reports, and creates a BattINFO JSON-LD metadata file.

### How to lay out data

Make one folder per sample (a "sample folder") and put raw data in it (not in subfolders). PyFlowBatt recognises each measurement from its file name, so the names need to contain `_OCV_`, `_PEIS_`, `_LSV_`, `_GCPL_`, `_CVpre` or `_CVpost`. If your files are named differently, you can change this in a `pyflowbatt.toml` file (see below).

You can run PyFlowBatt on one sample folder, or on a folder with many sample folders inside it:

```
my-experiment/               <- run pyflowbatt here
├── 261028_abcd_cell1/        <- a sample folder
│   ├── ..._01_OCV_CE4.mpr
│   ├── ..._02_PEIS_CE4.mpr
│   ├── ..._04_GCPL_CE4.mpr
│   ├── battinfo.xlsx        <- optional, from BattINFO Converter
│   └── results/             <- made by PyFlowBatt
├── 261028_abcd_cell2/       <- another sample folder
│   └── ...
└── combined_summary.xlsx    <- made by PyFlowBatt
```

Name each sample folder starting with the date and your initials, e.g. `250115_abcd_...`. PyFlowBatt uses the folder name as the sample name in the summaries.

Sample folders can be grouped into subfolders, but don't put a sample folder inside another sample folder.

### Zipping for Zenodo

If you use `--zip`, PyFlowBatt also makes a zip of everything, with a RO-Crate metadata file describing the files inside:
```
pyflowbatt --folder "path/to/your/folder" --zip
```

### Several folders at once

You can analyse several folders in one go. Each folder is analysed as if run on its own (including the zip, if used).
```
pyflowbatt --folder "path/to/X" "path/to/Y" "path/to/Z"
```
You can also combine all those summaries from multiple folders into one Excel file: add `--combined-summary` with an `.xlsx` file, or a folder to write `combined_summary.xlsx` into (`.` for the current folder).
```
pyflowbatt --folder "path/to/X" "path/to/Y" "path/to/Z" --combined-summary "path/to/all_samples.xlsx"
```
Its "Summary" sheet lists every sample from all the folders, and its "By folder" sheet puts each folder's average and standard deviation side by side.

### Checking before a long run

A full analysis can take a while. You can do a 'dry run' to check what files *would* be analysed, e.g.:
```
pyflowbatt --dry
```
```
pyflowbatt --dry --folder "path/to/your/folder" --zip
```
This is useful for checking everything is in order before running a long analysis.

### Settings

You can override some settings by adding a `pyflowbatt.toml` file to a sample folder, parent folder, or your home folder. Use `pyflowbatt init` to create a template file and see what can be modified.

## Using in Python

You can also use the functions in Python, e.g.

```python
# Use individual functions
from pyflowbatt import gcpl, lsv, cv
from pyflowbatt.read import read_to_bdf

df = read_to_bdf("path/to/my/gcpl-file")
df, cycle_df = gcpl.analyse(df)

cv_df = read_to_bdf("path/to/my/cv-file")
cv_df, cv_cycle_df, capacitance_mF = cv.analyse(cv_df)

lsv_df = read_to_bdf("path/to/my/lsv-file")
lsv_result_dict = lsv.analyse(lsv_df)

# Or run the full analysis on folders
from pyflowbatt.analysis import analyse_sample, analyse_all_samples
analyse_sample("path/to/sample/folder")
analyse_all_samples("path/to/parent/folder/of/many/samples")
```

## For contributors

If you find bugs, or want new features, open an *issue* on the GitHub page.

If you want to directly contribute to the project, it is easiest to use the tool 'uv':
```
git clone https://github.com/empaeconversion/pyflowbatt.git

cd pyflowbatt

uv sync
```
Then open this folder in an editor like VSCode.

You should always create a new branch before making edits, `main` is only for tested, working code that everyone can use.

E.g. make and switch to a new branch with
```
git checkout -b new-feature
```

You have now branched off the `main` PyFlowBatt into your own branch called e.g. `new-feature`. Now you can do whatever you like and it won't affect the `main` branch.

When you have made and committed some changes that add a feature or fix a problem, and you want to put them into `main`, open a *pull request* on GitHub.

