> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/data/preparing-data). For the upload workflow, see
[uploading data](/data/uploading).

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

<Note>
  **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](/data/preparing-data#time-not-cumulative).
</Note>

### 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](/data/preparing-data#incorrect-current-sign-convention)
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                                          |

<Note>
  **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.
</Note>

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

```json theme={null}
{"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.

### Unit notation

Units are stored in **PyBaMM notation**: `.`-separated atoms with optional
signed integer exponents, no `*`, `/`, or `**`. For example:

| Quantity        | PyBaMM notation                               |
| --------------- | --------------------------------------------- |
| Capacity        | `A.h`                                         |
| Areal loading   | `mg.cm-2`                                     |
| Specific energy | `W.h.kg-1`                                    |
| Concentration   | `mol.m-3`                                     |
| Conductivity    | `S.m-1`                                       |
| Single units    | `V`, `A`, `s`, `degC`, `ohm`, `mm`, `percent` |

**Pint-style strings are also accepted** on input and are normalized to
PyBaMM notation when stored. The following pairs are equivalent on submit:

| Pint input | Stored as  |
| ---------- | ---------- |
| `A*h`      | `A.h`      |
| `mg/cm**2` | `mg.cm-2`  |
| `W*h/kg`   | `W.h.kg-1` |
| `mol/m**3` | `mol.m-3`  |
| `S/m`      | `S.m-1`    |

This means existing payloads that use Pint syntax continue to work, but
values returned from the API will be in PyBaMM notation. Prefer PyBaMM
notation in new code so what you send matches what you read back.

```python theme={null}
# Both of these are accepted; the stored unit is "A.h" in either case.
client.cell_spec.update(
    cell_spec.id,
    ratings={"capacity": {"value": 2.0, "unit": "A.h"}},
)
client.cell_spec.update(
    cell_spec.id,
    ratings={"capacity": {"value": 2.0, "unit": "A*h"}},
)
```

## Step summaries

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

<Tip>
  Step summaries are **automatically generated** from your time series data
  during upload if you don't provide them yourself.
</Tip>

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

<CardGroup cols={2}>
  <Card title="Preparing data" icon="file-import" href="/data/preparing-data">
    Convert cycler files into this format with the ionworksdata library.
  </Card>

  <Card title="Uploading data" icon="upload" href="/data/uploading">
    Upload formatted data as cell specs, instances, and measurements.
  </Card>

  <Card title="Measurements" icon="flask" href="/data/measurements">
    The three measurement types and their fields.
  </Card>

  <Card title="Visualizing data" icon="chart-line" href="/data/visualizing">
    Explore uploaded data with the interactive viewer.
  </Card>
</CardGroup>