Data format

Recognized time series columns, units, current sign convention, EIS columns, and quantity format for battery cycling data

Ionworks Studio uses a standardized format for battery cycling data. This page is the reference for recognized columns, the quantity format for numeric values, and the sign conventions Ionworks assumes on upload.

For turning raw cycler files into this format, see preparing data. For the upload workflow, see uploading data.

Time series columns

The time series DataFrame contains high-resolution measurements from your cycling experiment. You can include any columns in your data; the columns below are recognized by the automatic step labeling system.

Column	Type	Description
Time [s]	float	Cumulative time in seconds (not reset per cycle)
Voltage [V]	float	Cell voltage
Current [A]	float	Current (positive = discharge, negative = charge)
Cycle count	int	Cumulative cycle number (0-indexed)
Step count	int	Cumulative step number across all cycles (0-indexed)
Temperature [degC]	float	Cell temperature
Cycle from cycler	int	Cycle number as reported by cycler
Step from cycler	int	Step number as reported by cycler
Discharge capacity [A.h]	float	Cumulative discharge capacity
Charge capacity [A.h]	float	Cumulative charge capacity
Discharge energy [W.h]	float	Cumulative discharge energy
Charge energy [W.h]	float	Cumulative charge energy

Time must be cumulative across cycles. If your cycler resets time to zero at the start of each cycle, convert it to cumulative time during processing. See preparing data — time not cumulative.

Custom columns

You can add any additional columns to your time series data. Custom columns are stored and available for visualization but aren’t used by the automatic step labeling system.

Current sign convention

Ionworks uses a consistent sign convention throughout:

• Positive current = discharge
• Negative current = charge

The validator rejects data that appears to use the opposite convention or whose convention cannot be determined (all values have the same sign). If your cycler uses a different convention, see preparing data — sign conventions for conversion helpers.

EIS and impedance data

If your measurement includes electrochemical impedance spectroscopy (EIS) data, the following columns are recognized:

Column	Type	Description
Frequency [Hz]	float	Excitation frequency
Z_Re [Ohm]	float	Real part of impedance
Z_Im [Ohm]	float	Imaginary part of impedance (negative for capacitive behavior)
Z_Mod [Ohm]	float	Impedance magnitude
Z_Phase [deg]	float	Impedance phase angle

Sign convention: Z_Im [Ohm] stores the raw imaginary part of impedance, which is typically negative for capacitive behavior. The Nyquist plot in Ionworks Studio automatically negates this value to display -Z_Im [Ohm] on the y-axis, following the standard electrochemistry convention. File readers (e.g., BioLogic, Gamry) handle this conversion automatically.

Cartesian / polar derivation

When your data includes Z_Mod [Ohm] and Z_Phase [deg] but is missing Z_Re [Ohm] or Z_Im [Ohm], Ionworks automatically derives the missing components:

• Z_Re = Z_Mod * cos(Z_Phase * π/180)
• Z_Im = Z_Mod * sin(Z_Phase * π/180)

This means you can upload impedance data in either Cartesian (Z_Re, Z_Im) or polar (Z_Mod, Z_Phase) form and Ionworks will ensure all four columns are available for analysis. Existing columns are never overwritten.

Quantity format

All numeric values with units use the format {"value": <number>, "unit": "<unit>"}. For example:

{"value": 2.0, "unit": "A*h"}

This format applies to cell specification ratings (capacity, voltage_min, etc.), cell instance measured_properties, and properties measurements. Plain strings and numbers without units are also accepted where appropriate.

Step summaries

Step summaries contain aggregated metrics for each step in the experiment. They enable efficient filtering and cycle-level analysis.

Step summaries are automatically generated from your time series data during upload if you don’t provide them yourself.

Automatically generated step summaries include columns like step_type (inferred as Rest, CC charge, CC discharge, CV, etc.), duration_s, voltage statistics (start_voltage_v, end_voltage_v, mean_voltage_v), current statistics, and capacity/energy totals for each step.

Next steps

Preparing data

Convert cycler files into this format with the ionworksdata library.

Uploading data

Upload formatted data as cell specs, instances, and measurements.

Measurements

The three measurement types and their fields.

Visualizing data

Explore uploaded data with the interactive viewer.