Step Analysis

Functions for analyzing and labeling battery cycling steps. This module provides tools to summarize time series data into step-level information, label steps by type (cycling, pulse, EIS), and annotate time series with step labels.

Core Functions

ionworksdata.steps.summarize(data: DataFrame | DataFrame) → DataFrame

Returns a DataFrame with information about each step in the data.

Parameters

datapd.DataFrame | pl.DataFrame

The data to get the step types for. Must contain “Step count” column. If “Cycle from cycler” is present, it will be used to calculate cycle count.

Returns

pl.DataFrame

A DataFrame with information about each step in the data. The output always includes a “Cycle count” column (defaults to 0 if no cycle information is available), “Cycle charge capacity [A.h]” and “Cycle discharge capacity [A.h]” columns, “Cycle charge energy [W.h]” and “Cycle discharge energy [W.h]” columns (if energy columns are present), and a “Cycle from cycler” column (only if provided in the input data).

ionworksdata.steps.identify(time_series: DataFrame | DataFrame) → list[dict]

Identify individual steps in battery cycling data.

This function processes a time series DataFrame and identifies distinct steps within battery cycling data by detecting changes in the “Step count” column. For each identified step, it extracts and calculates relevant metrics (voltage, current, capacity, etc.) and determines the step type.

Parameters

time_seriespd.DataFrame | pl.DataFrame

Battery cycling data with columns including “Step count”, “Time [s]”, ‘Voltage [V]’, ‘Current [A]’, etc.

Returns

list[dict]

List of dictionaries where each dictionary contains information about a step, including start/end indices, voltage, current, capacity, duration, and step type.

ionworksdata.steps.annotate(time_series: DataFrame | DataFrame, steps: DataFrame | DataFrame, column_names: list[str]) → DataFrame

Apply columns from the steps table to the time series.

Each time-series row is assigned the step’s value for each requested column, based on step “Start index” and “End index” (inclusive). Use this to attach step-level info (e.g. “Step count”, “Label”, “Step type”) to every row for downstream transforms or filtering.

Parameters

time_seriespl.DataFrame | pd.DataFrame

The time series to annotate. Row indices are 0 to n-1; steps must use the same index space (e.g. slice coordinates).

stepspl.DataFrame | pd.DataFrame

Steps with “Start index” and “End index” and the columns in column_names.

column_nameslist[str]

Columns to copy from steps onto the time series.

Returns

pl.DataFrame

The time series with the requested step columns added.

ionworksdata.steps.validate(steps: DataFrame | DataFrame, label_name: str) → bool

Validate the steps dataframe for a given label.

Parameters

stepspd.DataFrame | pl.DataFrame

The steps dataframe to validate.

label_namestr

The name of the label to validate.

Returns

bool

True if the steps dataframe is valid for the given label, False otherwise.

ionworksdata.steps.infer_type(step: dict, current_std_tol: float | None = None, voltage_std_tol: float | None = None, power_std_tol: float | None = None, rest_tol: float | None = None, eis_tol: float | None = None) → str

Infer the type of step based on its metrics.

Parameters

stepdict

A dictionary containing the calculated metrics and properties for the step.

current_std_tolfloat, optional

The tolerance for the standard deviation of the current below which the step is considered a constant current step. If None, uses the value from global settings.

voltage_std_tolfloat, optional

The tolerance for the standard deviation of the voltage below which the step is considered a constant voltage step. If None, uses the value from global settings.

power_std_tolfloat, optional

The tolerance for the standard deviation of the power below which the step is considered a constant power step. If None, uses the value from global settings.

rest_tolfloat, optional

The tolerance for the absolute value of the current below which the step is considered a rest step. If None, uses the value from global settings.

eis_tolfloat, optional

The tolerance for the absolute value of the frequency below which the step is considered an EIS step. If None, uses the value from global settings.

Returns

str

The type of step.

ionworksdata.steps.set_cycle_capacity(steps: DataFrame | dict) → DataFrame

Calculate the cycle capacity for each step in the data.

Cycles are identified by the “Cycle count” column.

Parameters

stepspl.DataFrame | dict

A DataFrame with information about each step in the data.

Returns

pl.DataFrame

The original DataFrame with the cycle capacity added.

ionworksdata.steps.set_cycle_energy(steps: DataFrame | dict) → DataFrame

Calculate the cycle energy for each step in the data.

Cycles are identified by the “Cycle count” column.

Parameters

stepspl.DataFrame | dict

A DataFrame with information about each step in the data.

Returns

pl.DataFrame

The original DataFrame with the cycle energy added.

Labeling Functions

ionworksdata.steps.label_cycling(steps: DataFrame | DataFrame, options: dict | None = None) → DataFrame

Label the “cycling” portion of the test.

Cycling is defined as constant current (and optionally constant voltage) steps where the capacity is greater than a certain percentage of the nominal cell capacity. Sets the “Label” column to “Cycling” and the “Group number” column to the group number. For cycling, a “group” is all the steps in one direction (including rest) - i.e. constant current discharge + rest is one group, constant current charge + rest is another group. The group number is incremented with each new group.

Parameters

stepspd.DataFrame | pl.DataFrame

The steps dataframe.

optionsdict, optional

Options for the labeling. The default is None, which uses the following default options:

  • “cell_metadata”: a dictionary of cell metadata. Required.

  • “constant current threshold”: the threshold for the capacity to be considered a constant current step. Default is 1/2.

Returns

pl.DataFrame

The steps dataframe with the cycling steps labeled.

ionworksdata.steps.label_pulse(steps: DataFrame | DataFrame, options: dict | None = None) → DataFrame

Label the “pulse” portion of the test.

Sets the “Label” column to either “GITT” or “HPPT” and the “Group number” column to the group number. For pulse, the group number increments from zero with each “long” pulse (i.e. the step which changes the SOC). If all groups in a contiguous block of pulse steps have one rest step, the block is labelled as “GITT”, otherwise it is labelled as “HPPT”.

Parameters

stepspd.DataFrame | pl.DataFrame

The steps dataframe.

optionsdict, optional

Options for the labeling. The default is None, which uses the following default options:

  • “cell_metadata”: a dictionary of cell metadata. Required.

  • “lower pulse capacity cutoff”: the minimum percentage capacity required for a step to be considered a pulse step. Default is 1 / 100.

  • “upper pulse capacity cutoff”: the maximum percentage capacity required for a step to be considered a pulse step. Default is 1 / 5.

  • “min pulses”: the minimum number of pulses required for the data to be considered valid. Default is 1.

  • “current direction”: the direction of the current for the pulse. Default is “discharge”. Other options are “charge”.

Returns

pl.DataFrame

The steps dataframe with the pulse steps labeled.

ionworksdata.steps.label_eis(steps: DataFrame | DataFrame, options: dict | None = None) → DataFrame

Label EIS steps.

Sets the “Label” column to “EIS” and the “Group number” column to the group number. For EIS, the group number increments from zero with each contiguous block of EIS steps.

Parameters

stepspd.DataFrame | pl.DataFrame

A step summary dataframe (as returned by iwdata.steps.summarize)

optionsdict, optional

Options for the labeling. No options are currently supported.

Returns

pl.DataFrame

The dataframe with the updated “Label” and “Group number” columns.