Process & upload cycler data

Convert a raw cycler export into the Ionworks standardized format and upload it as a time-series measurement with the Python SDK.

Turn a raw cycler export (Arbin, Maccor, Neware, Basytec, BioLogic, …) into the Ionworks standardized format and upload it as a measurement — all from Python.

Install and authenticate first: pip install ionworks-api and set IONWORKS_API_KEY (and IONWORKS_PROJECT_ID). See the Python API client page.

from ionworks import Ionworks
from ionworksdata import read

client = Ionworks()

# 1. Process the raw file into two standardized frames:
#    - time_series: one row per logged time point (Time [s], Voltage [V],
#      Current [A], Step count, ...)
#    - steps: one row per protocol step, with per-step summaries
#      (step/cycle indices, capacity, energy, min/max voltage, ...)
time_series, steps = read.time_series_and_steps("arbin_export.csv", reader="arbin")

# 2. Create-or-get the cell hierarchy: specification -> instance.
cell_spec = client.cell_spec.create_or_get({"name": "LGM50"})
cell_instance = client.cell_instance.create_or_get(cell_spec.id, {"name": "SN-001"})

# 3. Upload as a time-series measurement (idempotent; strict validation on).
measurement = client.cell_measurement.create_or_get(
    cell_instance.id,
    {
        "measurement": {"name": "cell_SN001_cycling"},
        "time_series": time_series,
        "steps": steps,
    },
    validate_strict=True,
)
print(measurement.id)

What’s happening

• time_series vs steps. time_series is the raw signal trace — one row per logged time point. steps is a compact per-step summary — one row per protocol step — carrying step/cycle indices and derived quantities (capacity, energy, voltage extremes) that read.time_series_and_steps computes as it parses. Steps are what most analyses group and filter on.
• ionworksdata.read has readers for the common cyclers; read.detect(path) auto-picks one. Prefer read.time_series_and_steps — it returns both frames and runs the full processing pipeline in one call.
• Current sign convention: Ionworks treats positive current as discharge. Different cyclers use different conventions, so check your source and flip the sign if needed (ionworksdata provides set_positive_current_for_discharge) before uploading.
• create_or_get is idempotent — re-running returns the existing spec/instance/measurement instead of duplicating it. A returned object (not the call merely completing) is the proof of success.

Learn more

• Preparing data and Reading cycler files
• Uploading measurements and Raw data
• Standardized data format