Input File Requirements¶

BatteryProc supports multiple input formats. This guide summarizes expectations for each, then details the Neware .xlsx structure.

Supported formats and expectations¶

Format	Delimiter/Encoding	Header	Notes (minimum columns after parse)
`.xlsx` (Neware)	n/a (Excel)	Sheets `record`, `cycle`, `unit`	Time, Voltage, Current, Capacity; see below
`.csv`	comma (`,`), UTF‑8	Required first row (leading `#` comment lines auto-skipped)	Detectable canonical column names; mapping can normalize
`.txt`	auto (tab preferred; falls back to comma/semicolon/pipe/whitespace), UTF‑8	Required first row (leading `#` comment lines auto-skipped)	Same as CSV
`.mpt` (BioLogic)	semicolon or tab; often Latin‑1	Header lines then table	Heuristics extract table; Voltage, Current, Time, Capacity where present

Notes: - A header row is required for delimited text. Use standard separators and encodings when possible. - Column names do not need to match exactly; the mapping system can normalize common variants. - Downstream calculations generally expect at minimum: time, voltage, current, and capacity-like columns.

See also: User Guide → Supported File Formats, and the developer guide on Adding a Parser.

To ensure batteryproc can successfully process your Neware .xlsx data files, it's important that they contain specific sheets and column headers. Here’s a guide to help you set up your files correctly:

Extending Mappings¶

BatteryProc supports a user-editable mapping configuration that standardizes sheet names, column names, and units across instruments.

Default config is packaged at batteryproc/config/column_mappings.yml.
Provide your own overrides via --mapping-file path/to/mapping.yml.

Schema overview: - sheets: logical sheet names → list of aliases. - instruments: profiles with: - columns: direct or regex patterns → standardized column names. - units: standardized column → {from: <unit>, factor: <float>} to scale from raw units.

Example override (YAML):

sheets:
    record: [record]
    cycle: [cycle]

instruments:
    default:
        columns:
            "(?i)^volt(age)?\\s*\(m?v\)$": "Voltage (V)"
            "(?i)^curr(ent)?\\s*\(m?a\)$": "Current (A)"
        units:
            "Voltage (V)": { from: mV, factor: 0.001 }
            "Current (A)": { from: mA, factor: 0.001 }

CLI usage: - batteryproc input.xlsx --mapping-file my_mappings.yml - Toggle token/regex heuristics (debug mappings): batteryproc input.xlsx --mapping-file my_mappings.yml --no-heuristic-map (default is --heuristic-map)

Notes: - Regex patterns must be quoted in YAML. Use single quotes or escape backslashes. - Legacy expectations for Voltage(V) and Current(mA) aliases are preserved automatically when the mapping config path is used. - Automatic unit conversions only trigger when the raw column name contains the source unit token (for example (mV) or (mA)). If your export uses generic labels such as Voltage, add an explicit mapping (e.g., Voltage (mV)) so the converter knows the starting unit. - Default mappings include common Neware header variants. Neware exports that omit mass-normalized values (e.g., only Capacity(mAh) instead of Spec. Cap.(mAh/g)) are supported; provide mass when prompted or ensure mass is discoverable in the test sheet for specific-capacity outputs.

Expected Excel Sheets¶

batteryproc looks for the following sheets in your Excel file:

1. `record` Sheet (Mandatory)¶

This is the most critical sheet, containing the detailed time-series data from your battery test. It should include columns like: - Cycle Index: The cycle number for each data point. - Step Index: The step number within a particular cycle. - Step Type: Describes the step (e.g., "Charge", "Discharge", "Rest"). batteryproc uses keywords like "chg", "dchg", and "rest" (case-insensitive) to identify what each step is doing. - Voltage(V): The voltage readings, in Volts. - Current(mA): The current readings, in milliAmps. - Time Data: You'll need a column for time. This can be: - Total Time: Representing the total elapsed time. This can be just seconds, or a time string like "HH:MM:SS". - OR Total Time(h:min:s): Specifically formatted as "hours:minutes:seconds". - Capacity Data: Columns for capacity are essential. You can provide this in two ways: - Spec. Cap.(mAh/g): This is for specific capacity in mAh/g and is generally what batteryproc prefers if available. - OR Cap.(mAh) or Capacity(mAh): These are for raw capacity in mAh. If you only have raw capacity, batteryproc might ask you to enter the active material mass when you run it, or it might assume a mass of 1g in some situations. For the most accurate specific capacity results, ensure your Neware software is set to output specific capacity, or be ready to provide the mass. - Energy Data (Optional but Recommended for Energy Metrics): If you want batteryproc to calculate energy-related metrics or generate energy plots, include: - Spec. Energy(mWh/g): Specific energy in mWh/g.

2. `cycle` Sheet (Mandatory)¶

This sheet should contain summary data for each cycle. - Required Columns: - Cycle Index: The cycle number for each row of summary data. - Capacity Data for Sanity Checks: batteryproc performs a "bad cell check" using capacity data from this sheet. It looks for one of these pairs of columns: - Chg. Spec. Cap.(mAh/g) AND DChg. Spec. Cap.(mAh/g) - OR Charge_mAh/g AND Discharge_mAh/g (Note: these latter names are often found in files that batteryproc has already processed, so they are less common for this check in a raw export from Neware).

3. `unit` Sheet (Mandatory)¶

While batteryproc might not extract specific data points from this sheet for its core calculations, its presence in the Excel file is required for the software to validate the file structure.

Optional Sheet for Advanced Features¶

`test` Sheet (Optional - for Step Plan Analysis)¶

If you want batteryproc to understand and use your specific testing procedure (the step plan), you can include a "test" sheet. - How to Structure It: - Somewhere in this sheet, there must be a cell containing the exact phrase "step plan" (it's not case-sensitive). - Below this "step plan" label, batteryproc expects to find a header row. This row should contain the names of your step plan columns (e.g., "Step Number", "Control Mode", "Set Value", "Cut-off Condition", etc. – whatever your Neware software exports for the step plan). - The rows immediately following this header should be your actual step plan data. - Step Plan Columns: The specific column names and data in your step plan are defined by your experiment and your Neware export settings. batteryproc will read them as they are.

By ensuring your .xlsx files are structured with these sheets and columns, you'll enable batteryproc to analyze your battery data effectively.

Time resets and low-current traces¶

Neware instruments often reset the reported time to 00:00:00 whenever the step index advances. You do not need to post-process these files before feeding them to BatteryProc. The normalisation pipeline unwraps per-step resets into a monotonic time_s column and records diagnostics (reset count, indices, offsets) in the time_resets metadata that later appears in cycle detection outputs as cycle_detection_time_resets. Expect the CLI to emit a downgraded warning that references TIME_REVERSAL; enable --strict-time-resets when you need that anomaly to remain fatal for audit runs.

The adaptive cycle-detection threshold is tuned from the absolute current trace, so sub-milliamp activity is still treated as “active” after time unwrapping. Metadata describing the derived threshold lives under cycle_detection_auto_threshold, and you can switch the heuristic on/off with --autotune-current-threshold or --no-autotune-current-threshold if a project requires fixed current gates.

CSV¶

CSV inputs must include a header row. Use UTF‑8 encoding and a comma (,) delimiter. Columns should correspond to canonical names (or be mappable via the column mapping system). Ensure capacity and time columns are present for metrics and plotting.

Contiguous leading comment lines whose first non-whitespace character is # are skipped automatically: the first non-comment line is treated as the header and the rest as data rows, so instrument exports that carry a # preamble (including # lines that contain commas) parse without manual pre-processing. A file consisting only of # comment lines with no data rows raises a ParserError rather than returning partial data.

TXT¶

TXT inputs are parsed with delimiter detection (tab is preferred; fallback to comma/semicolon/pipe/whitespace). A header row is required. As with CSV, contiguous leading # comment lines are skipped automatically (the first non-comment line becomes the header), so you no longer need to strip a # preamble by hand. Encoding should be UTF‑8 where possible.

MPT (BioLogic)¶

BioLogic .mpt files commonly use Latin‑1 and include an initial header section followed by a tabular block. BatteryProc applies heuristics to locate and parse the table. Where present, Voltage, Current, Time, and Capacity-like columns are extracted. Refer to instrument export options for a canonical layout.

Troubleshooting parsing¶

Ensure a header row is present in delimited inputs.
Verify the delimiter and encoding.
For Neware .xlsx, include record, cycle, and unit sheets.
Save .mpt with standard export options to retain tabular sections.
For stubborn cases, provide a custom mapping file and/or run with --debug.