cellpy.readers.instruments.base

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

Module Contents

Classes

AtomicLoad	Atomic loading class
AutoLoader	Main autoload class.
BaseLoader	Main loading class
TxtLoader	Main txt loading class (for sub-classing).

Functions

find_delimiter_and_start(file_name[, separators, ...])	Function to automatically detect the delimiter and what line the first data appears on.
query_csv(self, name[, sep, skiprows, header, ...])	function to query a csv file using pandas.read_csv.

Attributes

MINIMUM_SELECTION

class AtomicLoad

Atomic loading class

property fid

The unique file id

property is_db

Is the file stored in the database

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

instrument_name = 'atomic_loader'

copy_to_temporary()

Copy file to a temporary file

generate_fid(value=None)

Generate a unique file id

loader(*args, **kwargs)

The method that does the actual loading.

This method should be overwritten by the specific loader class.

loader_executor(*args, **kwargs)

Load the file

class 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.

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.

instrument_name = 'auto_loader'

abstract static get_headers_aux(raw: pandas.DataFrame) → dict

get_raw_limits()

Limits used to identify type of step.

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)

get_raw_units()

Units used by the instrument.

The internal cellpy units are given in the cellpy_units attribute.

Returns:

dictionary of units (str)

Example

A minimum viable implementation could look like this:

@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

loader(name: str | pathlib.Path, **kwargs: str) → cellpy.readers.core.Data

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

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: str | pathlib.Path) → pandas.DataFrame

register_configuration() → cellpy.readers.instruments.configurations.ModelParameters

Register and load model configuration

validate(data: cellpy.readers.core.Data) → cellpy.readers.core.Data

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

class BaseLoader

Bases: AtomicLoad

Main loading class

instrument_name = 'base_loader'

classmethod get_params(parameter: str | None) → 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

Limits used to identify type of step.

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

Units used by the instrument.

The internal cellpy units are given in the cellpy_units attribute.

Returns:

dictionary of units (str)

Example

A minimum viable implementation could look like this:

@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: cellpy.readers.core.Data) → cellpy.readers.core.Data

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

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

Loads data into a Data object and returns it

class TxtLoader(*args, **kwargs)

Bases: AutoLoader, abc.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.

model

short name of the (already implemented) sub-model.

Type:

str

sep

delimiter.

Type:

str

skiprows

number of lines to skip.

Type:

int

header

number of the header lines.

Type:

int

encoding

encoding.

Type:

str

decimal

character used for decimal in the raw data, defaults to ‘.’.

Type:

str

processors

pre-processing steps to take (before loading with pandas).

Type:

dict

post_processors

post-processing steps to make after loading the data, but before

Type:

dict

returning them to the caller.

include_aux

also parse so-called auxiliary columns / data. Defaults to False.

Type:

bool

keep_all_columns

load all columns, also columns that are not 100% necessary for cellpy to work.

Type:

bool

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

Parameters:

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'

raw_ext = '*'

parse_formatter_parameters(**kwargs)

Parse the formatter parameters.

parse_loader_parameters(auto_formatter=None, **kwargs)

Parse the loader parameters.

Parameters:

• auto_formatter – if True, the formatter will be set to auto-formatting.

• **kwargs – keyword arguments.

query_file(name)

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.

This function is fairly stupid. It splits the data into two parts, the (possible) header part (using the number of lines defined in 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).

Parameters:

• file_name – path to the file.

• separators – list of possible delimiters.

• checking_length_header – number of lines to check for header.

• checking_length_whole – number of lines to check for delimiter.

Returns:

the delimiter. first_index: the index of the first line with data.

Return type:

separator

query_csv(self, name, sep=None, skiprows=None, header=None, encoding=None, decimal=None, thousands=None)

function to query a csv file using pandas.read_csv.

Parameters:

• name – path to the file.

• sep – delimiter.

• skiprows – number of lines to skip.

• header – number of the header lines.

• encoding – encoding.

• decimal – character used for decimal in the raw data, defaults to ‘.’.

• thousands – character used for thousands in the raw data, defaults to ‘,’.

Returns:

pandas.DataFrame

MINIMUM_SELECTION = ['Data_Point', 'Test_Time', 'Step_Time', 'DateTime', 'Step_Index', 'Cycle_Index', 'Current',...