cellpy.readers.instruments package

Submodules

cellpy.readers.instruments.arbin module

arbin MS SQL Server data

class cellpy.readers.instruments.arbin_sql.DataLoader(*args, **kwargs)

Bases: BaseLoader

Class for loading arbin-data from MS SQL server.

static get_headers_aux()

Defines the so-called auxiliary table column headings for Arbin SQL Server

static get_headers_aux_global()

Defines the so-called auxiliary global column headings for Arbin SQL Server

static get_headers_global()

Defines the so-called global column headings for Arbin SQL Server

static get_headers_normal()

Defines the so-called normal column headings for Arbin SQL Server

static get_raw_limits()

returns a dictionary with resolution limits

static get_raw_units()

Include the settings for the units used by the instrument. This is needed for example when converting the capacity to a specific capacity. So far, it has been difficult to get any kind of consensus on what the most optimal units are for storing cycling data. Therefore, cellpy implements three levels of units: 1) the raw units that the data is loaded in already has and 2) the cellpy units used by cellpy when generating summaries and related information, and 3) output units that can be set to get the data in a specif unit when exporting or creating specific outputs such as ICA.

Comment 2022.09.11: still not sure if we should use raw units or cellpy units in the cellpy-files (.h5).

Currently, the summary is in cellpy units and the raw and step data is in raw units. If you have any input on this topic, let us know. What (at least I, i.e. jepe) would like to implement is to only use raw units in the cellpy-files. And rename the summary headers so that they don’t contain any reference to their units (e.g. renaming discharge_capacity_u_mAh_g to specific_discharge_capacity or discharge_capacity_specific). This will be a breaking change.

The units are defined w.r.t. the SI units (‘unit-fractions’; currently only units that are multiples of Si units can be used). For example, for current defined in mA, the value for the current unit-fraction will be 0.001.

Returns: dictionary containing the unit-fractions for current, charge, and mass

Comments to me:

This will be used to convert all values to the internal set cellpy units (given in xxxx). The units used by cellpy will be stored in the cellpy file. The original units will not be stored.

Example

@staticmethod def get_raw_units():

raw_units = {

“current”: 1.0, # A “charge”: 1.0, # Ah “mass”: 0.001, # g (i.e. units are given in mg) “voltage”: 1.0, # V “time”: 1.0, # sec “resistance”: 1.0, # Ohms “power”: 1.0, # W “energy”: 1.0, # Wh “length”: 1.0, # m “area”: 1.0, # m2 “temperature”: 1.0, # C

} return raw_units

The internal cellpy units are given in the

loader(name, **kwargs)

returns a Cell object with loaded data.

Loads data from arbin SQL server db.

Parameters

name (str) – name of the test

Returns

new_tests (list of data objects)

name = 'arbin_sql'

cellpy.readers.instruments.arbin_sql.check_get()

cellpy.readers.instruments.arbin_sql.check_loader()

cellpy.readers.instruments.arbin_sql.check_loader_from_outside()

cellpy.readers.instruments.arbin_sql.check_query()

cellpy.readers.instruments.arbin_sql.check_sql_loader(server: Optional[str] = None, tests: Optional[list] = None)

cellpy.readers.instruments.arbin_sql.from_arbin_to_datetime(n)

arbin MS SQL Server csv data

class cellpy.readers.instruments.arbin_sql_csv.DataLoader(*args, **kwargs)

Bases: BaseLoader

Class for loading arbin-data from MS SQL server.

static get_headers_aux(df)

Defines the so-called auxiliary table column headings for Arbin SQL Server csv

static get_headers_normal()

Defines the so-called normal column headings for Arbin SQL Server csv

static get_raw_limits()

returns a dictionary with resolution limits

static get_raw_units()

Include the settings for the units used by the instrument. This is needed for example when converting the capacity to a specific capacity. So far, it has been difficult to get any kind of consensus on what the most optimal units are for storing cycling data. Therefore, cellpy implements three levels of units: 1) the raw units that the data is loaded in already has and 2) the cellpy units used by cellpy when generating summaries and related information, and 3) output units that can be set to get the data in a specif unit when exporting or creating specific outputs such as ICA.

Comment 2022.09.11: still not sure if we should use raw units or cellpy units in the cellpy-files (.h5).

Currently, the summary is in cellpy units and the raw and step data is in raw units. If you have any input on this topic, let us know. What (at least I, i.e. jepe) would like to implement is to only use raw units in the cellpy-files. And rename the summary headers so that they don’t contain any reference to their units (e.g. renaming discharge_capacity_u_mAh_g to specific_discharge_capacity or discharge_capacity_specific). This will be a breaking change.

The units are defined w.r.t. the SI units (‘unit-fractions’; currently only units that are multiples of Si units can be used). For example, for current defined in mA, the value for the current unit-fraction will be 0.001.

Returns: dictionary containing the unit-fractions for current, charge, and mass

Comments to me:

This will be used to convert all values to the internal set cellpy units (given in xxxx). The units used by cellpy will be stored in the cellpy file. The original units will not be stored.

Example

@staticmethod def get_raw_units():

raw_units = {

“current”: 1.0, # A “charge”: 1.0, # Ah “mass”: 0.001, # g (i.e. units are given in mg) “voltage”: 1.0, # V “time”: 1.0, # sec “resistance”: 1.0, # Ohms “power”: 1.0, # W “energy”: 1.0, # Wh “length”: 1.0, # m “area”: 1.0, # m2 “temperature”: 1.0, # C

} return raw_units

The internal cellpy units are given in the

loader(name, **kwargs)

returns a Cell object with loaded data.

Loads data from arbin SQL server db.

Parameters

name (str) – name of the file

Returns

new_tests (list of data objects)

name = 'arbin_sql_csv'

raw_ext = 'csv'

cellpy.readers.instruments.arbin_sql_csv.test_csv_loader()

cellpy.readers.instruments.arbin_sql_csv.test_loader_from_outside()

cellpy.readers.instruments.arbin_sql_csv.test_seamless_files()

cellpy.readers.instruments.custom module

This module is used for loading data using the instrument=”custom” method. If no instrument_file is given (either directly or through the use of the :: separator), the default instrument file (yaml) will be used.

class cellpy.readers.instruments.custom.DataLoader(instrument_file=None, **kwargs)

Bases: AutoLoader, ABC

Class for loading data from txt files.

default_model = None

name = 'custom'

parse_formatter_parameters(**kwargs)

parse_loader_parameters(**kwargs)

pre_init()

query_file(name)

raw_ext = '*'

supported_models = None

cellpy.readers.instruments.custom.check_loader_from_outside_with_get()

cellpy.readers.instruments.biologics_mpr module

This file contains methods for importing Bio-Logic mpr-type files

class cellpy.readers.instruments.biologics_mpr.DataLoader(*args, **kwargs)

Bases: BaseLoader

Class for loading biologics-data from mpr-files.

dump(file_name, path)

Dumps the raw file to an intermediate hdf5 file.

This method can be used if the raw file is too difficult to load and it is likely that it is more efficient to convert it to an hdf5 format and then load it using the from_intermediate_file function.

Parameters

• file_name – name of the raw file

• path – path to where to store the intermediate hdf5 file (optional)

Returns

full path to stored intermediate hdf5 file information about the raw file (needed by the from_intermediate_file function)

static get_raw_limits()

Include the settings for how to decide what kind of step you are examining here.

The raw limits are ‘epsilons’ used to check if the current and/or voltage is stable (for example for galvanostatic steps, one would expect that the current is stable (constant) and non-zero). It is expected that different instruments (with different resolution etc.) have different ‘epsilons’.

Returns: the raw limits (dict)

static get_raw_units()

Include the settings for the units used by the instrument.

The units are defined w.r.t. the SI units (‘unit-fractions’; currently only units that are multiples of Si units can be used). For example, for current defined in mA, the value for the current unit-fraction will be 0.001.

Returns: dictionary containing the unit-fractions for current, charge, and mass

inspect(run_data)

inspect the file.

load(file_name)

Load a raw data-file

Parameters

file_name (path) –

Returns

loaded test

loader(file_name, bad_steps=None, **kwargs)

Loads data from biologics .mpr files.

Parameters

• file_name (str) – path to .res file.

• bad_steps (list of tuples) – (c, s) tuples of steps s (in cycle c) to skip loading.

Returns

new_tests (list of data objects)

name = 'biologics_mpr'

raw_ext = 'mpr'

repair(file_name)

try to repair a broken/corrupted file

cellpy.readers.instruments.biologics_mpr.datetime2ole(dt)

converts from datetime object to ole datetime float

cellpy.readers.instruments.biologics_mpr.ole2datetime(oledt)

converts from ole datetime float to datetime

cellpy.readers.instruments.base module

When you make a new loader you have to subclass the Loader class. Remember also to register it in cellpy.cellreader.

(for future development, not used very efficiently yet).

class cellpy.readers.instruments.base.AtomicLoad

Bases: object

Atomic loading class

name = 'atomic_loader'

class cellpy.readers.instruments.base.AutoLoader(*args, **kwargs)

Bases: BaseLoader

Main autoload class.

This class can be sub-classed if you want to make a data-reader for different type of “easily parsed” files (for example csv-files). The subclass needs to have at least one associated CONFIGURATION_MODULE defined and must have the following attributes as minimum:

default_model: str = NICK_NAME_OF_DEFAULT_CONFIGURATION_MODULE supported_models: dict = SUPPORTED_MODELS

where SUPPORTED_MODELS is a dictionary with {NICK_NAME : CONFIGURATION_MODULE_NAME} key-value pairs. Remark! the NICK_NAME must be in upper-case!

It is also possible to set these in a custom pre_init method:

@classmethod def pre_init(cls):

cls.default_model: str = NICK_NAME_OF_DEFAULT_CONFIGURATION_MODULE cls.supported_models: dict = SUPPORTED_MODELS

or turn off automatic registering of configuration:

@classmethod def pre_init(cls):

cls.auto_register_config = False # defaults to True

During initialisation of the class, if auto_register_config == True, it will dynamically load the definitions provided in the CONFIGURATION_MODULE.py located in the cellpy.readers.instruments.configurations folder/package.

static get_headers_aux(raw: DataFrame) → dict

get_raw_limits()

Include the settings for how to decide what kind of step you are examining here.

The raw limits are ‘epsilons’ used to check if the current and/or voltage is stable (for example for galvanostatic steps, one would expect that the current is stable (constant) and non-zero). It is expected that different instruments (with different resolution etc.) have different ‘epsilons’.

Returns: the raw limits (dict)

get_raw_units()

Include the settings for the units used by the instrument.

The units are defined w.r.t. the SI units (‘unit-fractions’; currently only units that are multiples of Si units can be used). For example, for current defined in mA, the value for the current unit-fraction will be 0.001.

Returns: dictionary containing the unit-fractions for current, charge, and mass

loader(name: Union[str, Path], **kwargs: str) → List[Cell]

returns a Cell object with loaded data.

Loads data from Maccor txt file (csv-ish).

Parameters

• name (str, pathlib.Path) – name of the file.

• kwargs (dict) – key-word arguments from raw_loader.

Returns

new_tests (list of data objects)

name = 'auto_loader'

abstract parse_formatter_parameters(**kwargs) → None

abstract parse_loader_parameters(**kwargs)

parse_meta() → dict

method that parses the data for meta-data (e.g. start-time, channel number, …)

pre_init() → None

abstract query_file(file_path: Union[str, Path]) → DataFrame

register_configuration() → ModelParameters

Register and load model configuration

validate(data: Cell) → Cell

validation of the loaded data, should raise an appropriate exception if it fails.

class cellpy.readers.instruments.base.BaseLoader

Bases: AtomicLoad

Main loading class

classmethod get_params(parameter: Optional[str]) → dict

Retrieves parameters needed for facilitating working with the instrument without registering it.

Typically, it should include the name and raw_ext.

Return: parameters or a selected parameter

abstract get_raw_limits() → dict

Include the settings for how to decide what kind of step you are examining here.

The raw limits are ‘epsilons’ used to check if the current and/or voltage is stable (for example for galvanostatic steps, one would expect that the current is stable (constant) and non-zero). If the (accumulated) change is less than ‘epsilon’, then cellpy interpret it to be stable. It is expected that different instruments (with different resolution etc.) have different resolutions and noice levels, thus different ‘epsilons’.

Returns: the raw limits (dict)

abstract static get_raw_units() → dict

Include the settings for the units used by the instrument. This is needed for example when converting the capacity to a specific capacity. So far, it has been difficult to get any kind of consensus on what the most optimal units are for storing cycling data. Therefore, cellpy implements three levels of units: 1) the raw units that the data is loaded in already has and 2) the cellpy units used by cellpy when generating summaries and related information, and 3) output units that can be set to get the data in a specif unit when exporting or creating specific outputs such as ICA.

Comment 2022.09.11: still not sure if we should use raw units or cellpy units in the cellpy-files (.h5).

Currently, the summary is in cellpy units and the raw and step data is in raw units. If you have any input on this topic, let us know. What (at least I, i.e. jepe) would like to implement is to only use raw units in the cellpy-files. And rename the summary headers so that they don’t contain any reference to their units (e.g. renaming discharge_capacity_u_mAh_g to specific_discharge_capacity or discharge_capacity_specific). This will be a breaking change.

The units are defined w.r.t. the SI units (‘unit-fractions’; currently only units that are multiples of Si units can be used). For example, for current defined in mA, the value for the current unit-fraction will be 0.001.

Returns: dictionary containing the unit-fractions for current, charge, and mass

Comments to me:

This will be used to convert all values to the internal set cellpy units (given in xxxx). The units used by cellpy will be stored in the cellpy file. The original units will not be stored.

Example

@staticmethod def get_raw_units():

raw_units = {

“current”: 1.0, # A “charge”: 1.0, # Ah “mass”: 0.001, # g (i.e. units are given in mg) “voltage”: 1.0, # V “time”: 1.0, # sec “resistance”: 1.0, # Ohms “power”: 1.0, # W “energy”: 1.0, # Wh “length”: 1.0, # m “area”: 1.0, # m2 “temperature”: 1.0, # C

} return raw_units

The internal cellpy units are given in the

static identify_last_data_point(data: Cell) → Cell

This method is used to find the last record in the data.

abstract loader(*args, **kwargs) → list

Loads data into a Cell object and returns it

name = 'base_loader'

class cellpy.readers.instruments.base.TxtLoader(*args, **kwargs)

Bases: AutoLoader, ABC

Main txt loading class (for sub-classing).

The subclass of a TxtLoader gets its information by loading model specifications from its respective module (cellpy.readers.instruments.configurations.<module>) or configuration file (yaml).

Remark that if you implement automatic loading of the formatter, the module / yaml-file must include all the required formatter parameters (sep, skiprows, header, encoding, decimal, thousands).

If you need more flexibility, try using the CustomTxtLoader or subclass directly from AutoLoader or Loader.

Constructor **kwargs:

model (str): short name of the (already implemented) sub-model. sep (str): delimiter. skiprows (int): number of lines to skip. header (int): number of the header lines. encoding (str): encoding. decimal (str): character used for decimal in the raw data, defaults to ‘.’. processors (dict): pre-processing steps to take (before loading with pandas). post_processors (dict): post-processing steps to make after loading the data, but before

returning them to the caller.

include_aux (bool): also parse so-called auxiliary columns / data. Defaults to False. keep_all_columns (bool): load all columns, also columns that are not 100% necessary for cellpy to work.

Remark that the configuration settings for the sub-model must include a list of column header names that should be kept if keep_all_columns is False (default).

Module - loader **kwargs:

sep (str): the delimiter (also works as a switch to turn on/off automatic detection of delimiter and

start of data (skiprows)).

name = 'txt_loader'

parse_formatter_parameters(**kwargs)

parse_loader_parameters(**kwargs)

query_file(name)

raw_ext = '*'

cellpy.readers.instruments.base.find_delimiter_and_start(file_name, separators=None, checking_length_header=30, checking_length_whole=200)

function to automatically detect the delimiter and what line the first data appears on.

Remark! This function is rather simple, it splits the data into to parts

(possible header part (checking_length_header) and the rest of the data). Then it counts the appearances of the different possible delimiters in the rest of the data part, and then selects a delimiter if it has unique counts for all the lines.

The first line is defined as where the delimiter is used same number of times (probably a header line).

cellpy.readers.instruments.base.query_csv(self, name, sep=None, skiprows=None, header=None, encoding=None, decimal=None, thousands=None)

cellpy.readers.instruments.pec module

cellpy.readers.instruments.maccor module

Maccor txt data

class cellpy.readers.instruments.maccor_txt.DataLoader(*args, **kwargs)

Bases: TxtLoader

Class for loading data from Maccor txt files.

default_model = 'one'

static get_headers_aux(raw)

Defines the so-called auxiliary table column headings

name = 'maccor_txt'

raw_ext = 'txt'

supported_models = {'FOUR': 'maccor_txt_four', 'KIT_COMMA_SIMBA': 'maccor_txt_two', 'KIT_SIMBA': 'maccor_txt_four', 'ONE': 'maccor_txt_one', 'S4000-KIT': 'maccor_txt_four', 'S4000-UBHAM': 'maccor_txt_three', 'S4000-WMG': 'maccor_txt_four', 'THREE': 'maccor_txt_three', 'TWO': 'maccor_txt_two', 'UBHAM_SIMBA': 'maccor_txt_three', 'WMG_SIMBA': 'maccor_txt_three', 'ZERO': 'maccor_txt_zero'}

validate(data)

A simple check that all the needed columns has been successfully loaded and that they get the correct type

cellpy.readers.instruments.maccor_txt.check_dev_loader(name=None, model=None)

cellpy.readers.instruments.maccor_txt.check_dev_loader2(name=None, model=None, sep=None, number=2)

cellpy.readers.instruments.maccor_txt.check_loader(name=None, number=1, model='one')

cellpy.readers.instruments.maccor_txt.check_loader_from_outside()

cellpy.readers.instruments.maccor_txt.check_loader_from_outside_with_get()

cellpy.readers.instruments.maccor_txt.check_loader_from_outside_with_get2()

cellpy.readers.instruments.maccor_txt.check_retrieve_file(n=1)

cellpy.readers.instruments.processors module

pre-processors

Pre-processing methods for instrument loaders.

All methods must implement the following parameters/arguments:

filename: Union[str, pathlib.Path], *args: str, **kwargs: str

All methods should return None (i.e. nothing).

cellpy.readers.instruments.processors.pre_processors.remove_empty_lines(filename: Union[str, Path], *args: str, **kwargs: str) → Path

Remove all the empty lines in the file.

The method saves to the same name as the original file, so it is recommended to work on a temporary copy of the file instead of the original file.

Parameters

• filename – path to the file.

• *args – None supported.

• **kwargs – None supported.

Returns

pathlib.Path of modified file

post-processors

Post-processing methods for instrument loaders.

All methods must implement the following parameters/arguments:

data: Cell object config_params: ModelParameters

All methods should return the modified Cell object.

You can access the individual parameters for the post processor from the config_params.post_processor[<name of post processor>].

cellpy.readers.instruments.processors.post_processors.convert_date_time_to_datetime(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.convert_step_time_to_timedelta(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.convert_test_time_to_timedelta(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.convert_units(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.cumulate_capacity_within_cycle(data: Cell, config_params: ModelParameters) → Cell

Cumulates the capacity within each cycle

cellpy.readers.instruments.processors.post_processors.date_time_from_test_time(data: Cell, config_params: ModelParameters) → Cell

add a date_time column (based on the test_time column).

cellpy.readers.instruments.processors.post_processors.get_column_names(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.remove_last_if_bad(data: Cell, config_params: ModelParameters) → Cell

Drop the last row if it contains more NaNs than second to last.

cellpy.readers.instruments.processors.post_processors.rename_headers(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.replace(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.select_columns_to_keep(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.set_cycle_number_not_zero(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.set_index(data: Cell, config_params: ModelParameters) → Cell

cellpy.readers.instruments.processors.post_processors.split_capacity(data: Cell, config_params: ModelParameters) → Cell

split capacity into charge and discharge

cellpy.readers.instruments.processors.post_processors.split_current(data: Cell, config_params: ModelParameters) → Cell

Split current into positive and negative

Module contents