API Documentation

Working With Cycler Data

class primed_data_processing.arbin_cycler.ArbinBatch(name: str = '', cells: list[primed_data_processing.arbin_cycler.ArbinCell] = [])

Represents a batch of cells that are tested together.

The cells in the batch can have different testing parameters and chemistries, the only requirement is that they are tested in the chamber at the same time.

add_cell(cell) → None

Add a cell object to the batch.

Parameters

cell : ArbinCell

ArbinCell to be added to the object.

class primed_data_processing.arbin_cycler.ArbinCell(cell_number: int, channel_number: int, cycles: list[primed_data_processing.arbin_cycler.ArbinCycle] = [], headers: list[str] = [])

Represents a cell (battery) in a given test where any number of ArbinCycle occur.

Attributes

cell_number : int

Number assigned to the cell for the test.

channel_number : int

Channel assigned to the cell for the test.

cycles : list[ArbinCycle]

List of ArbinCycle.

headers : list[str]

Name of column headers in the data. For example, Voltage(V).

Methods

add_cycle(cycle) → None

Add a cycle to the cell.

Parameters

cycle : ArbinCycle

ArbinCycle to be added to the object.

class primed_data_processing.arbin_cycler.ArbinCycle(cycle_index: int, steps: list[primed_data_processing.arbin_cycler.ArbinStep] = [], name: str = '', test_number: int | None = None)

Represents a cycle in a given test where any number of ArbinStep occur.

Attributes

cycle_index : int

The cycle number.

steps : list[ArbinStep]

List of ArbinStep in the cycle.

name : string

Name of the cycle. Default is ''.

test_number : int

The test number for the test that this cycle belongs too. Default is None.

Methods

add_step(step: ArbinStep) → None

Add a step to the list of steps in the cycle.

Parameters

step : ArbinStep

step to be added to the cycle.

get_eis_step(step_number: int) → list[primed_data_processing.gamry_eis.EisSweep]

Gets gamry EIS steps matching the chosen step number in the cycle.

Parameters

step_number : int

Step index to be found.

Returns

list[EisSweep]

List of EIS steps within the cycle matching step_number. Returns an empty list if there is no matches.

get_step(step_number: int) → list[primed_data_processing.arbin_cycler.ArbinStep | primed_data_processing.gamry_eis.EisSweep]

Gets arbin cycler steps matching the chosen step number in the cycle.

Parameters

step_number : int

Step index to be found.

Returns

list[ArbinStep]

List of steps within the cycle matching step_number. Returns an empty list if there is no matches.

class primed_data_processing.arbin_cycler.ArbinStep(step_index: int, step_type: str, name: str | None = None)

Represents a step in an Arbin MITS PRO test schedule.

An example of a step would be a constant current discharge from some beginning SOC to some ending SOC or voltage.

Attributes

name : str

Name of the step.

step_index : int

The step number.

step_type : str

The type of the step can be any of ‘initialization’, ‘characterization’, ‘degradation’.

data_dict : dict[str: any]

Dictionary of data that mimics the input file format. Keys are the column headers from an Arbin data csv and the values are the column data associated with the headers.

Methods

get_data_as_array() → array

Returns

numpy.ndarray

An array of the object attributes so that they form a table of step data.

get_data_as_dataframe() → DataFrame

Returns

pandas.DataFrame

A table of the object data such that it replicates the input data csv.

plot_step_column(feature: str) → figure

Plots the data for a given feature from this step.

Parameters

feature : str

Feature to be plotted such as Voltage(V). Must match a key in the data_dict attribute of this ArbinStep.

Working With EIS Data

class primed_data_processing.gamry_eis.EisCell(cell_number, channel_number, name='', eis_cycles=[])

Represents a cell (battery) in a given test where any number of EisCycle can occur.

Attributes

name : str

Name of the cell. Default is ''.

eis_cycles : list[EisCycle]

List of EisCycle objects representing all of the sweeps measured in a given cycle.

cell_number : int

The cell number from the test.

channel_number : int

The channel number from the test.

Methods

add_cycle(eis_cycle) → None

Parameters

eis_cycle : EisCycle

EisCycle to be added to the cell.

get_data_as_array() → array

Returns

numpy.ndarray

All EisCycles in the cell. Shape is z x m x n x 11 where z is the number of cycles, m is the number of sweeps, and n is the number of data points in the sweep. 11 is the number of measured parameters in the EIS sweep.

class primed_data_processing.gamry_eis.EisCycle(cycle_number: int, sweeps: list[primed_data_processing.gamry_eis.EisSweep] = [], name='')

Represents a cycle in a given test where any number of EisSweep can occur.

Attributes

cycle_number : int

The cycle number in the test.

sweeps : list[EisSweep]

List of EisSweep objects that occur in this cycle.

name : str optional, default is ''

Name of the object.

Methods

add_sweep(eis_sweep) → None

Add an EisSweep object to the cycle.

Parameters

eis_sweep : EisSweep

EisSweep object to be added to the cycle.

get_data_as_array() → array

Returns

numpy.ndarray

All EisSweeps in the cycle as a m x n x 11 array where m is the number of sweeps, n is the number of measurements, and 11 is the number of columns.

Can also be seen as an output of m EisSweep.get_data_as_array().

class primed_data_processing.gamry_eis.EisSweep(name: str, soc: float, step_index: int = 0)

Represents a single EIS sweep.

An EIS sweep is a sweep from some start frequency to some end frequency with a specified number of data points within each frequency decade. The sweep occurs at a specified SOC.

Attributes

name : str

Name of the eis sweep.

soc : float

State-of-charge of battery when eis measurement was taken. 0 <= soc <=1.

step_index : int

Index of the EIS step in the arbin test schedule. Default is 0.

date_time : str

Date and time of the measurement.

data_dict : dict[str: list[float]]

Dictionary containing the EIS measurement data.

Methods

get_data_as_array() → array

Returns

numpy.ndarray

Nx11 array where the columns are pt, time, freq, zreal, zimag, zsig, zmod, zphase, idc, vdc, ierange

get_data_as_dataframe() → DataFrame

Returns

pandas.DataFrame

Nx11 table where column headers are pt, time, freq, zreal, zimag, zsig, zmod, zphase, idc, vdc, ierange

make_first_quadrant_dict() → None

Makes an attribute named first_dict that contains only the data of the first quadrant of the Nyquist plot.

read_DTA_file(file_path: str) → None

Read a Gamry DTA output file and store its information in this EisSweep object.

Parameters

file_path : str

Absolute path to the Gamry DTA file.

Data Downloader

class primed_data_processing.cellbuilder.CellBuilder

This object builds the cell data structure from the raw Arbin data files.

Attributes

None

Methods

merge_B6_eis_data(eis_cells: list[primed_data_processing.gamry_eis.EisCell], arbin_cells: list[primed_data_processing.arbin_cycler.ArbinCell]) → None

Merge eis cells into the arbin cells. Ensures that eis steps are input into the correct ArbinCyles.

Eis steps will only be merged into the Arbin objects if their is a correspoinding ArbinCell with a matching channel number and cycle number.

Parameters

eis_cells : list[EisCell]

List of EisCell to have steps added to the ArbinCells.

arbin_cells : list[ArbinCell]

List of ArbinCell to have eis steps added to.

read_B6_csv_data(cell: ArbinCell, file_path: str, steps: dict[str, list[int]], verbose: bool = False) → None

Read raw Arbin test data from a csv file such that only the data according to the steps in steps is read and stored.

This method supports looping over multiple files, however it requires that the files are sorted into chronological order.

Parameters

cell : ArbinCell

Cell that the data is to be loaded to.

file_path : str

Path to an Arbin raw data file according to batch B6. Must be a .csv file.

steps : dict

Keys are the step type (see ArbinStep.__init__) and values are lists of step numbers to be read and stored.

verbose : bool

Optional bool for controlling how much info is printed during data processing. Default is False.

read_leaf_characterization_excel_data(file_path: str, steps: dict[str, list[int]], verbose: bool = False) → list[primed_data_processing.arbin_cycler.ArbinCell]

Load Nissan Leaf initial characterization data from the init_gen1_packX excel files.

Parameters

cell : ArbinCell

Cell that the data is to be loaded to.

file_path : str

Path to an Arbin raw data file according to batch B6. Must be a .csv file.

steps : dict

Keys are the step type (see ArbinStep.__init__) and values are lists of step numbers to be read and stored.

verbose : bool

Optional bool for controlling how much info is printed during data processing. Default is False.

Utility Functions

Author: Sean Buchanan

This module contains useful functions for processing Arbin and Gamry battery data.

These functions come up continuously in practice from users so they have been added to a useful common location.

primed_data_processing.primed_utils.assign_cell_cycle_numbers(batch: ArbinBatch, step_idx: int | None = None)

Assign cell and cycle numbers to the steps for ease of access when working with data.

Parameters

batch : ArbinBatch

ArbinBatch object containing the test data.

step_idx : int

Step number to assign cell and cycle numbers too.

primed_data_processing.primed_utils.assign_soe(step: int, soe_step: int, nom_e_cap: float, batch: ArbinBatch) → None

Calculate and assign the SOE to step step in an attribute named soe for all cells in batch.

Parameters

step : int

Step number to have soe added to

soe_step : int

Step containing the full discharge data used to calculate the soe.

nom_e_cap : float

Nominal energy capacity of the battery used for the test in Wh.

batch : ArbinBatch

Batch of cells containing the desired data.

primed_data_processing.primed_utils.assign_soh(step: int, soh_step: int, nom_cap: float, batch: ArbinBatch) → None

Calculate and assign the SOH to step step in an attribute named soh for all cells in batch.

Parameters

step : int

Step number to have soh added to

soh_step : int

Step containing the full discharge data used to calculate the soh.

nom_cap : float

Nominal capacity of the battery used for the test in Ah.

batch : ArbinBatch

Batch of cells containing the desired data.

primed_data_processing.primed_utils.assign_temp(eis_step: int, temp_step: int, batch: ArbinBatch, default_step_idx: int = -1, default_temp_idx: int = -1) → None

Assign cell temperature to the eis step from the temperature of temp_step.

Parameters

eis_step : int

Step number of the eis step

temp_step : int

Step number of the step with temperature data.

batch : ArbinBatch

ArbinBatch object with the test data.

default_step_idx : int, optional

Index of the list of steps within the cycle. Default is -1.

default_temp_idx : int, optional

Index of the list of temperatures within the step. Default is -1.

primed_data_processing.primed_utils.filter_by_soh(steps: list[primed_data_processing.arbin_cycler.ArbinStep] | dict[slice(<class 'int'>, list[primed_data_processing.arbin_cycler.ArbinStep], None)], soh_range: float, soh_lower: int = 77, soh_upper: int = 101) → dict[slice(<class 'int'>, list[primed_data_processing.arbin_cycler.ArbinStep], None)]

Filter steps in steps such that only the steps with a SOH within the bounds of lower and upper are retained.

This function requires that all steps in steps have a soh attribute; see assign_soh.

Parameters

steps : list[ArbinStep] | dict[int: list[ArbinStep]]

ArbinSteps containing soh attributes to be sorted

soh_range : float

Width of SOH bins to sort steps into. If soh_range = 1 then steps will be sorted into bins from 77-78,78-79….,100-101 etc.

soh_lower : int, optional

Lower SOH bound for sorting.

soh_upper : int

Upper SOH bound for sorting.

Returns

dict[int: list[ArbinStep]]

Dictionary with key of the lower bound for each range and values of all the steps that match that soh range.

primed_data_processing.primed_utils.filter_by_temp(step: int, temp_range: tuple | list, batch: ArbinBatch) → dict[slice(<class 'int'>, list[primed_data_processing.arbin_cycler.ArbinStep], None)]

Filter steps in batch such that only the steps with a temperature within the bounds of temp_range are retained.

This function requires that all steps in steps have a temperature attribute; see assign_temp.

Parameters

step : int

Step number in batch object that has the temperature attribute.

temp_range : tuple | list

Element zero is the lower temperature bound and element 1 is the upper temperature bound.

batch : ArbinBatch

ArbinBatch that contains the test data. See primed_data_processing package.

Returns

dict[int: list[ArbinStep]]

Dictionary with key of the cell channel number and values of list of step data within the temperature range.

primed_data_processing.primed_utils.get_first_quadrant_data(step: int, batch: ArbinBatch) → None

Make a dictionary containing only the first quadrant eis data. See ArbinStep.make_first_quadrant_dict().

Parameters

step : int

Step number to get first quadrant data from.

batch : ArbinBatch

ArbinBatch object containing the test data.

primed_data_processing.primed_utils.load_B6T10(cell_builder: ~primed_data_processing.cellbuilder.CellBuilder, prepath: str, channel_numbers: list | tuple, cell_numbers: list | tuple, steps: dict[slice(<class 'str'>, list[int], None)]) → ArbinBatch

Load the entire B6T10/B6T15 dataset.

Parameters

cell_builder : CellBuilder

CellBuilder used to access data reading methods.

prepath : str

path to the folder containing all battery data.

channel_numbers : list | tuple

Channel numbers to be loaded.

cell_numbers : list | tuple

Cell number of channels to be loaded. Required to be in order correspondin to the channel numbers.

steps : dict[str: list[int]]

Steps to be loaded.

primed_data_processing.primed_utils.load_B6T10_eis(T10_eis_folder: str, T15_eis_folder: str, channel_numbers: list | tuple, cell_numbers: list | tuple) → list[primed_data_processing.gamry_eis.EisCell]

Load eis data from batch B6 and test 10 and 15 into a data object.

Parameters

T10_eis_folder : str

Absolute path to the folder containing test 10 eis data.

T15_eis_folder : str

Absolute path to the folder containing test 15 eis data.

channel_numbers : list | tuple

Iterable containing the channel numbers to be read into the data object.

cell_numbers : list | tuple

Iterable containing the cell numbers to be read into the data object.

Returns

list[EisCell]

List of EisCell objects for each cell in the folder directories.

primed_data_processing.primed_utils.load_B6T11(cell_builder: ~primed_data_processing.cellbuilder.CellBuilder, prepath: str, channel_numbers: list | tuple, cell_numbers: list | tuple, steps: dict[slice(<class 'str'>, list[int], None)]) → ArbinBatch

Load the entire B6T11/B6T16 dataset.

Parameters

cell_builder : CellBuilder

CellBuilder used to access data reading methods.

prepath : str

path to the folder containing all battery data.

channel_numbers : list | tuple

Channel numbers to be loaded.

cell_numbers : list | tuple

Cell number of channels to be loaded. Required to be in order correspondin to the channel numbers.

steps : dict[str: list[int]]

Steps to be loaded.

primed_data_processing.primed_utils.load_files_from_dir(cell_builder: ~primed_data_processing.cellbuilder.CellBuilder, arbin_cells: list[primed_data_processing.arbin_cycler.ArbinCell], sorted_dir: list[bytes], prepath: str, folder_name: str, steps: dict[slice(<class 'str'>, list[int], None)], channel_idx: int) → None

Load all csv files in a directory.

Parameters

cell_builder : CellBuilder

CellBuilder used to access data reading methods.

arbin_cells : list[ArbinCell]

list of arbin cells to add data to.

sorted_dir : list[bytes]

list of files in the directory sorted by chronological order.

prepath : str

path to the folder containing all battery data.

folder_name : str

name of the folder to be read.

steps : dict[str: list[int]]

dictionary of steps to be read.

channel_idx : int

Which channel to load data from.