Data Transformation

ionworksdata.transform.get_cumulative_step_number(data: DataFrame | DataFrame, options: dict | None = None) → Series

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

Parameters

datapl.DataFrame | pd.DataFrame

The data to assign step numbers to.

optionsdict, 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

pl.Series

The step numbers as an integer Series starting at 0.

ionworksdata.transform.set_cumulative_step_number(data: DataFrame, **kwargs) → DataFrame

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

Parameters

datapl.DataFrame

The data to add the step number to.

kwargs

Additional keyword arguments to pass to get_cumulative_step_number.

Returns

pl.DataFrame

The data with the step number added.

ionworksdata.transform.set_step_count(data: DataFrame | DataFrame, options: dict | None = None) → DataFrame

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

Parameters

datapl.DataFrame | pd.DataFrame

The data to assign step count to.

optionsdict, 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

pl.DataFrame

The data with “Step count” column added.

ionworksdata.transform.get_cumulative_cycle_number(data: DataFrame, options: dict | None = None) → Series

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

Parameters

datapl.DataFrame

The data to assign cycle count to.

optionsdict, 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

pl.Series

The cumulative cycle numbers.

ionworksdata.transform.set_cumulative_cycle_number(data: DataFrame, **kwargs) → DataFrame

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

Parameters

datapl.DataFrame

The data to add the cycle number to.

kwargs

Additional keyword arguments to pass to get_cumulative_cycle_number.

Returns

pl.DataFrame

The data with the cycle number added.

ionworksdata.transform.set_cycle_count(data: DataFrame) → DataFrame

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

datapl.DataFrame

The data to assign cycle count to.

Returns

pl.DataFrame

The data with “Cycle count” column added.

ionworksdata.transform.reset_time(data: DataFrame) → DataFrame

Reset the time to start at zero

Parameters

datapl.DataFrame

The data to reset the time for.

ionworksdata.transform.offset_duplicate_times(data: DataFrame, offset: float = 1e-06) → DataFrame

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

datapl.DataFrame

The data to remove duplicate time values from.

offsetfloat, optional

The amount to offset the duplicate time values by.

ionworksdata.transform.set_capacity(data: DataFrame, options: dict | None = None) → DataFrame

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

datapl.DataFrame

The data to calculate the capacity for.

optionsdict, optional

Additional options to pass to the function. The default is None.

Returns

pl.DataFrame

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

ionworksdata.transform.set_net_capacity(data: DataFrame, options: dict | None = None) → DataFrame

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

Parameters

datapl.DataFrame

The data to calculate the net capacity for.

optionsdict, optional

Additional options to pass to the function. The default is None.

Returns

pl.DataFrame

The data with the net capacity added.

ionworksdata.transform.set_nominal_soc(data: DataFrame, cell_metadata: dict, options: dict | None = None) → DataFrame

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

datapl.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_metadatadict

The metadata for the cell. Should have a key “Nominal cell capacity [A.h]” or “Nominal cell capacity [mA.h.cm-2]”

optionsdict, optional

Additional options to pass to the function. The default is None.

Returns

pl.DataFrame

The data with the nominal SOC added.

ionworksdata.transform.convert_current_density_to_total_current(data: DataFrame, metadata: dict) → DataFrame

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

Parameters

datapl.DataFrame

The data to convert. Should have a column “Current [mA.cm-2]”.

metadatadict

The metadata for the data. Should have a key “Electrode area [cm2]”.

Returns

pl.DataFrame

The data with the current converted to A.

ionworksdata.transform.convert_total_current_to_current_density(data: DataFrame, metadata: dict) → DataFrame

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

Parameters

datapl.DataFrame

The data to convert. Should have a column “Current [A]”.

metadatadict

The metadata for the data. Should have a key “Electrode area [cm2]”.

Returns

pl.DataFrame

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

ionworksdata.transform.set_positive_current_for_discharge(data: DataFrame, options: dict | None = None) → DataFrame

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

datapl.DataFrame

The data to set the current direction for.

optionsdict, optional

Additional options to pass to the function. The default is None.

Returns

pl.DataFrame

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

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

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

Parameters

datapl.DataFrame

The data to remove outliers from.

columnstr

The column to calculate the z-score for.

z_thresholdfloat, optional

The z-score threshold to use for removing outliers. The default is 3.

data_rangeslice, 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

pl.DataFrame

The data with the outliers removed.