cellpy.readers.instruments package

Subpackages

Submodules

cellpy.readers.instruments.arbin_res module

cellpy.readers.instruments.arbin_sql module

arbin MS SQL Server data

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

Bases: BaseLoader

Class for loading arbin-data from MS SQL server.

static get_headers_aux()[source]

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

static get_headers_aux_global()[source]

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

static get_headers_global()[source]

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

static get_headers_normal()[source]

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

static get_raw_limits()[source]

returns a dictionary with resolution limits

static get_raw_units()[source]

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

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.

The internal cellpy units are given in the cellpy_units attribute.

Returns

dictionary of units (str)

Example

A minimum viable implementation:

@staticmethod
def get_raw_units():
    raw_units = dict()
    raw_units["current"] = "A"
    raw_units["charge"] = "Ah"
    raw_units["mass"] = "g"
    raw_units["voltage"] = "V"
    return raw_units
instrument_name = 'arbin_sql'
loader(name, **kwargs)[source]

returns a Data 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)

cellpy.readers.instruments.arbin_sql.check_get()[source]
cellpy.readers.instruments.arbin_sql.check_loader()[source]
cellpy.readers.instruments.arbin_sql.check_loader_from_outside()[source]
cellpy.readers.instruments.arbin_sql.check_query()[source]
cellpy.readers.instruments.arbin_sql.check_sql_loader(server: Optional[str] = None, tests: Optional[list] = None)[source]
cellpy.readers.instruments.arbin_sql.from_arbin_to_datetime(n)[source]

cellpy.readers.instruments.arbin_sql_7 module

cellpy.readers.instruments.arbin_sql_csv module

arbin MS SQL Server csv data

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

Bases: BaseLoader

Class for loading arbin-data from MS SQL server.

static get_headers_aux(df)[source]

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

static get_headers_normal()[source]

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

static get_raw_limits()[source]

returns a dictionary with resolution limits

static get_raw_units()[source]

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

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.

The internal cellpy units are given in the cellpy_units attribute.

Returns

dictionary of units (str)

Example

A minimum viable implementation:

@staticmethod
def get_raw_units():
    raw_units = dict()
    raw_units["current"] = "A"
    raw_units["charge"] = "Ah"
    raw_units["mass"] = "g"
    raw_units["voltage"] = "V"
    return raw_units
instrument_name = 'arbin_sql_csv'
loader(name, **kwargs)[source]

returns a Data 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)

raw_ext = 'csv'
cellpy.readers.instruments.arbin_sql_csv.check_seamless_files()[source]
cellpy.readers.instruments.arbin_sql_csv.test_csv_loader()[source]
cellpy.readers.instruments.arbin_sql_csv.test_loader_from_outside()[source]

cellpy.readers.instruments.arbin_sql_h5 module

arbin MS SQL Server exported h5 data

class cellpy.readers.instruments.arbin_sql_h5.DataLoader(*args, **kwargs)[source]

Bases: BaseLoader

Class for loading arbin-data from MS SQL server.

static get_headers_aux(df)[source]

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

static get_headers_normal()[source]

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

static get_raw_limits()[source]

returns a dictionary with resolution limits

static get_raw_units()[source]

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

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.

The internal cellpy units are given in the cellpy_units attribute.

Returns

dictionary of units (str)

Example

A minimum viable implementation:

@staticmethod
def get_raw_units():
    raw_units = dict()
    raw_units["current"] = "A"
    raw_units["charge"] = "Ah"
    raw_units["mass"] = "g"
    raw_units["voltage"] = "V"
    return raw_units
instrument_name = 'arbin_sql_h5'
loader(name, **kwargs)[source]

returns a Data object with loaded data.

Loads data from arbin SQL server h5 export.

Parameters

name (str) – name of the file

Returns

data object

raw_ext = 'h5'
cellpy.readers.instruments.arbin_sql_h5.check_get()[source]

cellpy.readers.instruments.arbin_sql_xlsx module

arbin MS SQL Server csv data

class cellpy.readers.instruments.arbin_sql_xlsx.DataLoader(*args, **kwargs)[source]

Bases: BaseLoader

Class for loading arbin-data from MS SQL server.

static get_headers_aux(df)[source]

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

static get_headers_normal()[source]

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

static get_raw_limits()[source]

returns a dictionary with resolution limits

static get_raw_units()[source]

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

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.

The internal cellpy units are given in the cellpy_units attribute.

Returns

dictionary of units (str)

Example

A minimum viable implementation:

@staticmethod
def get_raw_units():
    raw_units = dict()
    raw_units["current"] = "A"
    raw_units["charge"] = "Ah"
    raw_units["mass"] = "g"
    raw_units["voltage"] = "V"
    return raw_units
instrument_name = 'arbin_sql_xlsx'
loader(name, **kwargs)[source]

returns a Data object with loaded data.

Loads data from arbin SQL server db.

Parameters

name (str) – name of the file

Returns

data object

raw_ext = 'xlsx'

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[source]

Bases: object

Atomic loading class

copy_to_temporary()[source]

Copy file to a temporary file

property fid

The unique file id

generate_fid(value=None)[source]

Generate a unique file id

instrument_name = 'atomic_loader'
property is_db

Is the file stored in the database

loader(*args, **kwargs)[source]

The method that does the actual loading.

This method should be overwritten by the specific loader class.

loader_executor(*args, **kwargs)[source]

Load the file

property name

The name of the file to be loaded

property refuse_copying

Should the file be copied to a temporary file

property temp_file_path

The name of the file to be loaded if copied to a temporary file

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

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.

Attributes can be set during initialisation of the class as **kwargs that are then handled by the parse_formatter_parameters method.

Remark that some also can be provided as arguments to the loader method and will then automatically be “transparent” to the cellpy.get function. So if you would like to give the user access to modify these arguments, you should implement them in the parse_loader_parameters method.

static get_headers_aux(raw: DataFrame) → dict[source]
get_raw_limits()[source]

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()[source]

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

instrument_name = 'auto_loader'
loader(name: Union[str, Path], **kwargs: str) → Data[source]

returns a Data object with loaded data.

Loads data from a 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)

abstract parse_formatter_parameters(**kwargs) → None[source]
abstract parse_loader_parameters(**kwargs)[source]
parse_meta() → dict[source]

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

pre_init() → None[source]
abstract query_file(file_path: Union[str, Path]) → DataFrame[source]
register_configuration() → ModelParameters[source]

Register and load model configuration

validate(data: Data) → Data[source]

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

class cellpy.readers.instruments.base.BaseLoader[source]

Bases: AtomicLoad

Main loading class

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

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[source]

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[source]

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

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.

The internal cellpy units are given in the cellpy_units attribute.

Returns

dictionary of units (str)

Example

A minimum viable implementation:

@staticmethod
def get_raw_units():
    raw_units = dict()
    raw_units["current"] = "A"
    raw_units["charge"] = "Ah"
    raw_units["mass"] = "g"
    raw_units["voltage"] = "V"
    return raw_units
static identify_last_data_point(data: Data) → Data[source]

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

instrument_name = 'base_loader'
abstract loader(*args, **kwargs) → list[source]

Loads data into a Data object and returns it

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

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:

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:

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

instrument_name = 'txt_loader'
parse_formatter_parameters(**kwargs)[source]
parse_loader_parameters(**kwargs)[source]
query_file(name)[source]
raw_ext = '*'
cellpy.readers.instruments.base.find_delimiter_and_start(file_name, separators=None, checking_length_header=30, checking_length_whole=200)[source]

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)[source]

cellpy.readers.instruments.biologics_mpr module

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)[source]

Bases: AutoLoader, ABC

Class for loading data from txt files.

default_model = None
instrument_name = 'custom'
parse_formatter_parameters(**kwargs)[source]
parse_loader_parameters(**kwargs)[source]
pre_init()[source]
query_file(name)[source]
raw_ext = '*'
supported_models = None
cellpy.readers.instruments.custom.check_loader_from_outside_with_get()[source]

cellpy.readers.instruments.ext_nda_reader module

class cellpy.readers.instruments.ext_nda_reader.DataLoader(*args, **kwargs)[source]

Bases: BaseLoader

Class for using the NDA loader by Frederik Huld (Beyonder).

static get_params(parameter=None)[source]

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

get_raw_limits()[source]

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()[source]

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

instrument_name = 'neware_nda'
loader(file_name, *args, **kwargs)[source]

Loads data into a DataSet object and returns it

cellpy.readers.instruments.ext_nda_reader.load_nda(*args, **kwargs)[source]

cellpy.readers.instruments.local_instrument module

This module is used for loading data using the corresponding Local yaml file with definitions on how the data should be loaded. This loader is based on the TxtLoader and can only be used to load csv-type files

class cellpy.readers.instruments.local_instrument.DataLoader(instrument_file=None, **kwargs)[source]

Bases: TxtLoader

Class for loading data from txt files.

default_model = None
instrument_name = 'local_instrument'
pre_init()[source]
raw_ext = '*'
supported_models = None

cellpy.readers.instruments.maccor_txt module

Maccor txt data

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

Bases: TxtLoader

Class for loading data from Maccor txt files.

default_model = 'one'
static get_headers_aux(raw)[source]

Defines the so-called auxiliary table column headings

instrument_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)[source]

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)[source]
cellpy.readers.instruments.maccor_txt.check_dev_loader2(name=None, model=None, sep=None, number=2)[source]
cellpy.readers.instruments.maccor_txt.check_loader(name=None, number=1, model='one')[source]
cellpy.readers.instruments.maccor_txt.check_loader_from_outside()[source]
cellpy.readers.instruments.maccor_txt.check_loader_from_outside_with_get()[source]
cellpy.readers.instruments.maccor_txt.check_loader_from_outside_with_get2()[source]
cellpy.readers.instruments.maccor_txt.check_retrieve_file(n=1)[source]

cellpy.readers.instruments.neware_txt module

Neware txt data - with explanations how it was implemented.

  1. Update SUPPORTED_MODELS, raw_ext and default_model

  2. Add instrument to prms.py

    1. create the boxed item:

      Neware = {“default_model”: “UIO”} Neware = box.Box(Neware)

      …

    2. add it to Instruments:

      Instruments = InstrumentsClass( … Neware=Neware )

    3. Update the dataclass in prms.py:

      @dataclass class InstrumentsClass(CellPyConfig):

      tester: str custom_instrument_definitions_file: Union[str, None] Arbin: box.Box Maccor: box.Box Neware: box.Box

  3. (optionally) add Neware defaults to .cellpy_prms_default.conf

  4. Create instrument configuration file in readers/instruments/configurations

    formatters states normal_headers_renaming_dict file_info raw_units post_processors

  5. Put a file in test_data and create at least one test.

class cellpy.readers.instruments.neware_txt.DataLoader(*args, **kwargs)[source]

Bases: TxtLoader

Class for loading data from Neware txt files.

default_model = 'one'
static get_headers_aux(raw)[source]

Defines the so-called auxiliary table column headings

instrument_name = 'neware_txt'
raw_ext = 'csv'
supported_models = {'UIO': 'neware_txt_zero'}
validate(data)[source]

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

cellpy.readers.instruments.pec_csv module

pec csv-type data files

class cellpy.readers.instruments.pec_csv.DataLoader(*args, **kwargs)[source]

Bases: BaseLoader

Main loading class

get_raw_limits()[source]

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()[source]

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

instrument_name = 'pec_csv'
loader(file_name, bad_steps=None, **kwargs)[source]

Loads data into a Data object and returns it

raw_ext = 'csv'
static timestamp_to_seconds(timestamp)[source]

Module contents