Data Transformation

ionworks.data.transform.get_cumulative_step_number(data: DataFrame | DataFrame, options: dict | None = None) → Series[source]

Assign a cumulative step number to each row in the data.

Parameters:

  • data (pl.DataFrame | pd.DataFrame) – The data to assign step numbers to.

  • options (dict, optional) –

    Options for assigning step numbers. The default is None, which uses the following default options:

    • method: The method to use for assigning step numbers. Default is status. Options are:

      • status: Assigns a new step number each time the status changes.

      • current sign: Assigns a new step number each time the sign of the current divided by the absolute maximum current changes more than 1e-2.

      • step column: Assigns a new step number each time the numeric value in the step column changes (see step column option).

    • current units: The format of the current. Default is total. Options are:

      • total: The current is in units of A.

      • density: The current is in units of mA.cm-2.

    • zero current tol: Tolerance for considering current as zero when using current sign method. Values below this fraction of max current are treated as zero. Default: value from global settings.

    • step column: The column to use for assigning step numbers if using the step column method. Default is Step number.

    • group EIS steps: Whether to group EIS steps together as a single step. If False, and method is current sign an EIS experiment at a single state of charge will have a large number of steps (the step number will change each time the current sign changes). Default: True.

    • EIS tolerance: The tolerance for considering a frequency as an EIS step. Default: 1e-8.

Returns:

The step numbers as an integer Series starting at 0.

Return type:

pl.Series

ionworks.data.transform.set_cumulative_step_number(data: DataFrame, **kwargs) → DataFrame[source]

Add a column with the cumulative step number to the data.

Parameters:

  • data (pl.DataFrame) – The data to add the step number to.

  • kwargs – Additional keyword arguments to pass to get_cumulative_step_number.

Returns:

The data with the step number added.

Return type:

pl.DataFrame

ionworks.data.transform.set_step_count(data: DataFrame | DataFrame, options: dict | None = None) → DataFrame[source]

Assign a cumulative step number “Step count” to each row in the data by detecting changes in the “Step from cycler” column.

Parameters:

  • data (pl.DataFrame | pd.DataFrame) – The data to assign step count to.

  • options (dict, optional) –

    Additional options to pass to the function. The default is None, which uses the following default options:

    • method: The method to use for assigning step count. Default is step column. Options are:

      • step column: Assigns a new step number each time the numeric value in the step column changes (see step column option).

    • step column: The column to use for assigning step numbers if using the step column method. Default is Step from cycler.

Returns:

The data with “Step count” column added.

Return type:

pl.DataFrame

ionworks.data.transform.get_cumulative_cycle_number(data: DataFrame, options: dict | None = None) → Series[source]

Assign a cumulative cycle number “Cycle count” to each row in the data.

Parameters:

  • data (pl.DataFrame) – The data to assign cycle count to.

  • options (dict, optional) –

    Additional options to pass to the function. The default is None, which uses the following default options:

    • method: The method to use for assigning cycle count. Default is cycle column. Options are:

      • cycle column: Assigns a new cycle number each time the numeric value in the cycle column changes (see cycle column option).

    • cycle column: The column to use for assigning cycle numbers. Default is Cycle number.

Returns:

The cumulative cycle numbers.

Return type:

pl.Series

ionworks.data.transform.set_cumulative_cycle_number(data: DataFrame, **kwargs) → DataFrame[source]

Add a column with the cumulative cycle number to the data.

Parameters:

  • data (pl.DataFrame) – The data to add the cycle number to.

  • kwargs – Additional keyword arguments to pass to get_cumulative_cycle_number.

Returns:

The data with the cycle number added.

Return type:

pl.DataFrame

ionworks.data.transform.set_cycle_count(data: DataFrame) → DataFrame[source]

Assign a cumulative cycle number “Cycle count” to each row in the data by detecting changes in the “Cycle from cycler” column. If “Cycle from cycler” doesn’t exist, sets all values to 0.

Parameters:

data (pl.DataFrame) – The data to assign cycle count to.

Returns:

The data with “Cycle count” column added.

Return type:

pl.DataFrame

ionworks.data.transform.reset_time(data: DataFrame) → DataFrame[source]

Reset the time to start at zero

Parameters:

data (pl.DataFrame) – The data to reset the time for.

ionworks.data.transform.offset_duplicate_times(data: DataFrame, offset: float = 1e-06) → DataFrame[source]

Offset duplicate time values by a small amount. This is preferable to removing the duplicate time values because removing duplicate time values can lead to missing steps in the data.

Parameters:

  • data (pl.DataFrame) – The data to remove duplicate time values from.

  • offset (float, optional) – The amount to offset the duplicate time values by.

ionworks.data.transform.set_capacity(data: DataFrame, options: dict | None = None) → DataFrame[source]

Calculate discharge and charge capacity for the data and assign them to new columns called “Discharge capacity [A.h]” and “Charge capacity [A.h]” Drops the single “Capacity [A.h]” column if it exists.

Parameters:

  • data (pl.DataFrame) – The data to calculate the capacity for.

  • options (dict, optional) – Additional options to pass to the function. The default is None.

Returns:

The data with discharge and charge capacity columns added, and single capacity column removed if it existed.

Return type:

pl.DataFrame

ionworks.data.transform.set_energy(data: DataFrame, options: dict | None = None) → DataFrame[source]

Calculate discharge and charge energy for the data and assign them to new columns called “Discharge energy [W.h]” and “Charge energy [W.h]” Drops the single “Energy [W.h]” column if it exists.

Parameters:

  • data (pl.DataFrame) – The data to calculate the energy for.

  • options (dict, optional) – Additional options to pass to the function. The default is None.

Returns:

The data with discharge and charge energy columns added, and single energy column removed if it existed.

Return type:

pl.DataFrame

ionworks.data.transform.get_cycle_cumulative(data: DataFrame, column: str) → Series[source]

Re-accumulate a per-step running quantity so it resets per cycle instead.

column restarts at every step boundary, as set_capacity and set_energy produce it. Each row gains the final value of every earlier step in its cycle, so the result runs through a cycle and restarts at its first step. A step belongs to the cycle it starts in, as in steps.summarize, so the last value in a cycle equals the steps table’s per-cycle total. Null and NaN rows stay as they are and contribute nothing to later steps.

Parameters:

  • data (pl.DataFrame) – Time series with “Step count”, “Cycle count” and column.

  • column (str) – The per-step running column to re-accumulate, e.g. “Discharge capacity [A.h]”.

Returns:

The cycle-cumulative values, one per row of data, named column.

Return type:

pl.Series

Raises:

ValueError – If “Step count”, “Cycle count” or column is missing from data.

ionworks.data.transform.set_cycle_cumulative_capacity(data: DataFrame, options: dict | None = None) → DataFrame[source]

Add discharge and charge capacity accumulated from the start of each cycle.

Adds “Cycle discharge capacity [A.h]” and “Cycle charge capacity [A.h]” (or [mA.h.cm-2] with density units). Unlike “Discharge capacity [A.h]”, which restarts at every step, these run across all steps of a cycle and restart at its first step. They differ from steps.set_cycle_capacity, which writes one per-cycle total per step. See get_cycle_cumulative().

Parameters:

  • data (pl.DataFrame) – Time series with “Step count”, “Cycle count” and the per-step discharge and charge capacity columns. Run set_capacity() first if they are absent.

  • options (dict, optional) – Options selecting the capacity units. The default is None (A.h).

Returns:

The data with the two cycle capacity columns added.

Return type:

pl.DataFrame

ionworks.data.transform.set_cycle_cumulative_energy(data: DataFrame) → DataFrame[source]

Add discharge and charge energy accumulated from the start of each cycle.

Adds “Cycle discharge energy [W.h]” and “Cycle charge energy [W.h]”, the energy counterparts of set_cycle_cumulative_capacity().

Parameters:

data (pl.DataFrame) – Time series with “Step count”, “Cycle count”, “Discharge energy [W.h]” and “Charge energy [W.h]”. Run set_energy() first if they are absent.

Returns:

The data with the two cycle energy columns added.

Return type:

pl.DataFrame

ionworks.data.transform.set_net_capacity(data: DataFrame, options: dict | None = None) → DataFrame[source]

Calculate the net capacity for the data and assign it to a new column called “Capacity [A.h]”.

Parameters:

  • data (pl.DataFrame) – The data to calculate the net capacity for.

  • options (dict, optional) – Additional options to pass to the function. The default is None.

Returns:

The data with the net capacity added.

Return type:

pl.DataFrame

ionworks.data.transform.set_nominal_soc(data: DataFrame, cell_metadata: dict, options: dict | None = None) → DataFrame[source]

Calculate the nominal SOC for the data and assign it to a new column called “Nominal SOC”. SOC is calculated based on net capacity (discharge - charge).

Parameters:

  • data (pl.DataFrame) – The data to calculate the nominal SOC for. Must have columns “Discharge capacity [A.h]” and “Charge capacity [A.h]” (or mA.h.cm-2). If they don’t exist, use set_capacity to calculate them first.

  • cell_metadata (dict) – The metadata for the cell. Should have a key “Nominal cell capacity [A.h]” or “Nominal cell capacity [mA.h.cm-2]”

  • options (dict, optional) – Additional options to pass to the function. The default is None.

Returns:

The data with the nominal SOC added.

Return type:

pl.DataFrame

ionworks.data.transform.convert_current_density_to_total_current(data: DataFrame, metadata: dict) → DataFrame[source]

Convert the current density from mA.cm-2 to A

Parameters:

  • data (pl.DataFrame) – The data to convert. Should have a column “Current [mA.cm-2]”.

  • metadata (dict) – The metadata for the data. Should have a key “Electrode area [cm2]”.

Returns:

The data with the current converted to A.

Return type:

pl.DataFrame

ionworks.data.transform.convert_total_current_to_current_density(data: DataFrame, metadata: dict) → DataFrame[source]

Convert the total current from A to mA.cm-2

Parameters:

  • data (pl.DataFrame) – The data to convert. Should have a column “Current [A]”.

  • metadata (dict) – The metadata for the data. Should have a key “Electrode area [cm2]”.

Returns:

The data with the current converted to mA.cm-2.

Return type:

pl.DataFrame

ionworks.data.transform.set_positive_current_for_discharge(data: DataFrame, options: dict | None = None) → DataFrame[source]

Identify whether positive current is charging or discharging, then make sure that positive current is discharging and negative current is charging.

Three paths:

  1. All currents same sign (cycler recording absolute values) and a mode column (e.g. "Status") is present with charge/discharge labels — use the mode column to negate charge rows.

  2. All currents same sign but no mode column — apply per-step sign correction using voltage response to classify each step as charge or discharge.

  3. Mixed-sign currents (normal case) — apply the original global mean voltage-response transform across the entire measurement.

Parameters:

  • data (pl.DataFrame) – The data to set the current direction for.

  • options (dict, optional) – Additional options to pass to the function. The default is None.

Returns:

The data with the current direction set to positive current is discharging.

Return type:

pl.DataFrame

ionworks.data.transform.remove_outliers(data: DataFrame, column: str, z_threshold: float = 3, data_range: slice | None = None) → DataFrame[source]

Remove outliers from the data based on the z-score of a column

Parameters:

  • data (pl.DataFrame) – The data to remove outliers from.

  • column (str) – The column to calculate the z-score for.

  • z_threshold (float, optional) – The z-score threshold to use for removing outliers. The default is 3.

  • data_range (slice, optional) – The range of data points to consider for outlier detection. If None, all points are used. Use Python’s slice notation, e.g., slice(0, 100) for first 100 points, slice(-100, None) for last 100 points.

Returns:

The data with the outliers removed.

Return type:

pl.DataFrame