Step Analysis

Functions for analyzing battery cycling steps. This module provides tools to summarize time series data into step-level information and annotate time series with step-level columns.

Core Functions

ionworks.data.steps.summarize(data: DataFrame | DataFrame, *, cell_spec: Any = None) → DataFrame[source]

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

Parameters:

  • data (pd.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.

  • cell_spec (dict or object, optional) – The cell specification (e.g. the API client’s CellSpecification). Preferred: with its ratings.capacity, rest and constant-current thresholds are C/1000 and C/200 instead of 1 % of the largest absolute current in the data, which a single current spike can distort.

Returns:

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).

Return type:

pl.DataFrame

ionworks.data.steps.identify(time_series: DataFrame | DataFrame, *, cell_spec: Any = None) → list[dict][source]

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_series (pd.DataFrame | pl.DataFrame) – Battery cycling data with columns including “Step count”, “Time [s]”, ‘Voltage [V]’, ‘Current [A]’, etc.

  • cell_spec (dict or object, optional) – The cell specification; see summarize().

Returns:

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

Return type:

list[dict]

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

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”, “Step type”) to every row for downstream transforms or filtering.

Parameters:

  • time_series (pl.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).

  • steps (pl.DataFrame | pd.DataFrame) – Steps with “Start index” and “End index” and the columns in column_names.

  • column_names (list[str]) – Columns to copy from steps onto the time series.

Returns:

The time series with the requested step columns added.

Return type:

pl.DataFrame

ionworks.data.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[source]

Infer the type of step based on its metrics.

Parameters:

  • step (dict) – A dictionary containing the calculated metrics and properties for the step.

  • current_std_tol (float, 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_tol (float, 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_tol (float, 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_tol (float, 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_tol (float, 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:

The type of step.

Return type:

str

ionworks.data.steps.set_cycle_capacity(steps: DataFrame | dict) → DataFrame[source]

Calculate the cycle capacity for each step in the data.

Cycles are identified by the “Cycle count” column.

Parameters:

steps (pl.DataFrame | dict) – A DataFrame with information about each step in the data.

Returns:

The original DataFrame with the cycle capacity added.

Return type:

pl.DataFrame

ionworks.data.steps.set_cycle_energy(steps: DataFrame | dict) → DataFrame[source]

Calculate the cycle energy for each step in the data.

Cycles are identified by the “Cycle count” column.

Parameters:

steps (pl.DataFrame | dict) – A DataFrame with information about each step in the data.

Returns:

The original DataFrame with the cycle energy added.

Return type:

pl.DataFrame