cellpy.readers package

Subpackages

Submodules

cellpy.readers.cellreader module

Datareader for cell testers and potentiostats.

This module is used for loading data and databases created by different cell testers. Currently it only accepts arbin-type res-files (access) data as raw data files, but we intend to implement more types soon. It also creates processed files in the hdf5-format.

Example

>>> d = CellpyData()
>>> d.loadcell(names = [file1.res, file2.res]) # loads and merges the runs
>>> voltage_curves = d.get_cap()
>>> d.save("mytest.hdf")
class cellpy.readers.cellreader.CellpyData(filenames=None, selected_scans=None, profile=False, filestatuschecker=None, tester=None, initialize=False)[source]

Bases: object

Main class for working and storing data.

This class is the main work-horse for cellpy where all the functions for reading, selecting, and tweaking your data is located. It also contains the header definitions, both for the cellpy hdf5 format, and for the various cell-tester file-formats that can be read. The class can contain several cell-tests and each test is stored in a list. If you see what I mean…

cells

list of DataSet objects.

Type

list

property cell

returns the DataSet instance

check()[source]

Returns False if no datasets exists or if one or more of the datasets are empty

check_file_ids(rawfiles, cellpyfile, detailed=False)[source]

Check the stats for the files (raw-data and cellpy hdf5).

This function checks if the hdf5 file and the res-files have the same timestamps etc to find out if we need to bother to load .res -files.

Parameters

  • cellpyfile (str) – filename of the cellpy hdf5-file.

  • rawfiles (list of str) – name(s) of raw-data file(s).

  • detailed (bool) – return a dict containing True or False for each individual raw-file

Returns

False if the raw files are newer than the cellpy hdf5-file

(update needed).

True if update is not needed.

If detailed is True it returns a dict containing True or False for each

individual raw-file.

Return type

If detailed is False

property cycle_mode
property dataset

returns the DataSet instance

dev_update(file_names=None, **kwargs)[source]
dev_update_from_raw(file_names=None, data_points=None, **kwargs)[source]

This method is under development. Using this to develop updating files with only new data.

dev_update_loadcell(raw_files, cellpy_file=None, mass=None, summary_on_raw=False, summary_ir=True, summary_ocv=False, summary_end_v=True, force_raw=False, use_cellpy_stat_file=None, nom_cap=None, selector=None, **kwargs)[source]
dev_update_make_steps(**kwargs)[source]
dev_update_make_summary(**kwargs)[source]
dev_update_merge()[source]
drop_edges(start, end)[source]

Select middle part of experiment (CellpyData object) from cycle number ‘start’ to ‘end

drop_from(cycle=None)[source]

Select first part of experiment (CellpyData object) up to cycle number ‘cycle’

drop_to(cycle=None)[source]

Select last part of experiment (CellpyData object) from cycle number ‘cycle’

property empty

gives True if the CellpyData object is empty (or un-functional)

from_raw(file_names=None, pre_processor_hook=None, post_processor_hook=None, **kwargs)[source]

Load a raw data-file.

Parameters

  • file_names (list of raw-file names) – uses CellpyData.file_names if None. If the list contains more than one file name, then the runs will be merged together.

  • pre_processor_hook (callable) – function that will be applied to the data within the loader.

  • post_processor_hook (callable) – function that will be applied to the cellpy.Dataset object after initial loading.

Keyword Args for merging:
recalc (bool): set to false if you don’t want cellpy to automatically shift cycle number

and time (e.g. add last cycle number from previous file to the cycle numbers in the next file).

Other keywords depending on loader:
[ArbinLoader]:
bad_steps (list of tuples): (c, s) tuples of steps s (in cycle c)

to skip loading.

dataset_number (int): the data set number to select if you are dealing

with arbin files with more than one data-set.

data_points (tuple of ints): load only data from data_point[0] to

data_point[1] (use None for infinite). NOT IMPLEMENTED YET.

from_res(filenames=None, check_file_type=True)[source]

Convenience function for loading arbin-type data into the datastructure.

Parameters

  • filenames – ((lists of) list of raw-file names): uses cellpy.file_names if None. If list-of-list, it loads each list into separate datasets. The files in the inner list will be merged.

  • check_file_type (bool) – check file type if True (res-, or cellpy-format)

get_cap(cycle=None, dataset_number=None, method='back-and-forth', insert_nan=None, shift=0.0, categorical_column=False, label_cycle_number=False, split=False, interpolated=False, dx=0.1, number_of_points=None, ignore_errors=True, dynamic=False, inter_cycle_shift=True, interpolate_along_cap=False, **kwargs)[source]

Gets the capacity for the run.

Parameters

  • cycle (int) – cycle number.

  • method (string) –

    how the curves are given “back-and-forth” - standard back and forth; discharge

    (or charge) reversed from where charge (or discharge) ends.

    ”forth” - discharge (or charge) continues along x-axis. “forth-and-forth” - discharge (or charge) also starts at 0

    (or shift if not shift=0.0)

  • insert_nan (bool) – insert a np.nan between the charge and discharge curves. Defaults to True for “forth-and-forth”, else False

  • shift – start-value for charge (or discharge) (typically used when plotting shifted-capacity).

  • categorical_column – add a categorical column showing if it is charge or discharge.

  • dataset_number (int) – test number (default first) (usually not used).

  • label_cycle_number (bool) – add column for cycle number (tidy format).

  • split (bool) – return a list of c and v instead of the default that is to return them combined in a DataFrame. This is only possible for some specific combinations of options (neither categorical_column=True or label_cycle_number=True are allowed).

  • interpolated (bool) – set to True if you would like to get interpolated data (typically if you want to save disk space or memory). Defaults to False.

  • dx (float) – the step used when interpolating.

  • number_of_points (int) – number of points to use (over-rides dx) for interpolation (i.e. the length of the interpolated data).

  • ignore_errors (bool) – don’t break out of loop if an error occurs.

  • dynamic – for dynamic retrieving data from cellpy-file. [NOT IMPLEMENTED YET]

  • inter_cycle_shift (bool) – cumulative shifts between consecutive cycles. Defaults to True.

  • interpolate_along_cap (bool) – interpolate along capacity axis instead of along the voltage axis. Defaults to False.

Returns

pandas.DataFrame ((cycle) voltage, capacity, (direction (-1, 1)))

unless split is explicitly set to True. Then it returns a tuple with capacity (mAh/g) and voltage.

get_ccap(cycle=None, dataset_number=None, converter=None, **kwargs)[source]

Returns charge_capacity (in mAh/g), and voltage.

get_cell(n=0)[source]
get_converter_to_specific(dataset=None, mass=None, to_unit=None, from_unit=None)[source]

get the conversion value to use when calculating specific values (e.g mAh/g).

Parameters

  • dataset – DataSet object

  • mass – mass of electrode (for example active material in mg)

  • to_unit – (float) unit of input, f.ex. if unit of charge is mAh and unit of mass is g, then to_unit for charge/mass will be 0.001 * 1.0 = 0.001

  • from_unit – (float) unit of output, f.ex. if unit of charge is mAh and unit of mass is g, then to_unit for charge/mass will be 1.0 / 0.001 = 1000.0

Returns

multiplier (float) from_unit / to_unit / mass

get_current(cycle=None, dataset_number=None, full=True)[source]

Returns current (in mA).

Parameters

  • cycle – cycle number (all cycles if None)

  • dataset_number – first dataset if None

  • full – valid only for cycle=None (i.e. all cycles), returns the full pandas.Series if True, else a list of pandas.Series

Returns

pandas.Series (or list of pandas.Series if cycle=None og full=False)

get_cycle_numbers(dataset_number=None, steptable=None, rate=None, rate_on=None, rate_std=None, rate_column=None, inverse=False)[source]

Get a list containing all the cycle numbers in the test.

Parameters

  • rate (float) – the rate to filter on. Remark that it should be given as a float, i.e. you will have to convert from C-rate to the actual numeric value. For example, use rate=0.05 if you want to filter on cycles that has a C/20 rate.

  • rate_on (str) – only select cycles if based on the rate of this step-type (e.g. on=”charge”).

  • rate_std (float) – allow for this inaccuracy in C-rate when selecting cycles

  • rate_column (str) – column header name of the rate column,

  • inverse (bool) – select steps that does not have the given C-rate.

Returns

numpy.ndarray of cycle numbers.

get_cycle_numbers_old(dataset_number=None, steptable=None)[source]

Get a list containing all the cycle numbers in the test.

get_datetime(cycle=None, dataset_number=None, full=True)[source]
get_dcap(cycle=None, dataset_number=None, converter=None, **kwargs)[source]

Returns discharge_capacity (in mAh/g), and voltage.

get_diagnostics_plots(dataset_number=None, scaled=False)[source]
get_ir(dataset_number=None)[source]

Get the IR data (Deprecated).

get_mass(set_number=None)[source]
get_number_of_cycles(dataset_number=None, steptable=None)[source]

Get the number of cycles in the test.

get_number_of_tests()[source]
get_ocv(cycles=None, direction='up', remove_first=False, interpolated=False, dx=None, number_of_points=None)[source]

get the open circuit voltage relaxation curves.

Parameters

  • cycles (list of ints or None) – the cycles to extract from (selects all if not given).

  • direction ("up", "down", or "both") – extract only relaxations that is performed during discharge for “up” (because then the voltage relaxes upwards) etc.

  • remove_first – remove the first relaxation curve (typically, the first curve is from the initial rest period between assembling the cell to the actual testing/cycling starts)

  • interpolated (bool) – set to True if you want the data to be interpolated (e.g. for creating smaller files)

  • dx (float) – the step used when interpolating.

  • number_of_points (int) – number of points to use (over-rides dx) for interpolation (i.e. the length of the interpolated data).

Returns

A pandas.DataFrame with cycle-number, step-number, step-time, and

voltage columns.

get_step_numbers(steptype='charge', allctypes=True, pdtype=False, cycle_number=None, dataset_number=None, trim_taper_steps=None, steps_to_skip=None, steptable=None)[source]

Get the step numbers of selected type.

Returns the selected step_numbers for the selected type of step(s).

Parameters

  • steptype (string) – string identifying type of step.

  • allctypes (bool) – get all types of charge (or discharge).

  • pdtype (bool) – return results as pandas.DataFrame

  • cycle_number (int) – selected cycle, selects all if not set.

  • dataset_number (int) – test number (default first) (usually not used).

  • trim_taper_steps (integer) – number of taper steps to skip (counted from the end, i.e. 1 means skip last step in each cycle).

  • steps_to_skip (list) – step numbers that should not be included.

  • steptable (pandas.DataFrame) – optional steptable

Returns

A dictionary containing a list of step numbers corresponding

to the selected steptype for the cycle(s).

Returns a pandas.DataFrame instead of a dict of lists if pdtype is

set to True. The frame is a sub-set of the step-table frame (i.e. all the same columns, only filtered by rows).

Example

>>> my_charge_steps = CellpyData.get_step_numbers(
>>>    "charge",
>>>    cycle_number = 3
>>> )
>>> print my_charge_steps
{3: [5,8]}
get_summary(dataset_number=None, use_summary_made=False)[source]

Retrieve summary returned as a pandas DataFrame.

get_timestamp(cycle=None, dataset_number=None, in_minutes=False, full=True)[source]

Returns timestamps (in sec or minutes (if in_minutes==True)).

Parameters

  • cycle – cycle number (all if None)

  • dataset_number – first dataset if None

  • in_minutes – return values in minutes instead of seconds if True

  • full – valid only for cycle=None (i.e. all cycles), returns the full pandas.Series if True, else a list of pandas.Series

Returns

pandas.Series (or list of pandas.Series if cycle=None og full=False)

get_voltage(cycle=None, dataset_number=None, full=True)[source]

Returns voltage (in V).

Parameters

  • cycle – cycle number (all cycles if None)

  • dataset_number – first dataset if None

  • full – valid only for cycle=None (i.e. all cycles), returns the full pandas.Series if True, else a list of pandas.Series

Returns

pandas.Series (or list of pandas.Series if cycle=None og full=False)

initialize()[source]
inspect_nominal_capacity(cycles=None)[source]

Method for estimating the nominal capacity

Parameters

cycles (list of ints) – the cycles where it is assumed that the cell reaches nominal capacity.

Returns

Nominal capacity (float).

static is_empty(v)[source]

Create a link to a cellpy file.

If the file is very big, it is sometimes better to work with the data out of memory (i.e. on disk). A CellpyData object with a linked file will in most cases work as a normal object. However, some of the methods might be disabled. And it will be slower.

Notes

2020.02.08 - maybe this functionality is not needed and can be replaced

by using dask or similar?

load(cellpy_file, parent_level=None, return_cls=True, accept_old=True, selector=None)[source]

Loads a cellpy file.

Parameters

  • cellpy_file (path, str) – Full path to the cellpy file.

  • parent_level (str, optional) – Parent level. Warning! Deprecating this soon!

  • return_cls (bool) – Return the class.

  • accept_old (bool) – Accept loading old cellpy-file versions. Instead of raising WrongFileVersion it only issues a warning.

  • () (selector) – under development

Returns

cellpy.CellPyData class if return_cls is True

load_step_specifications(file_name, short=False, dataset_number=None)[source]

Load a table that contains step-type definitions.

This function loads a file containing a specification for each step or for each (cycle_number, step_number) combinations if short==False. The step_cycle specifications that are allowed are stored in the variable cellreader.list_of_step_types.

loadcell(raw_files, cellpy_file=None, mass=None, summary_on_raw=False, summary_ir=True, summary_ocv=False, summary_end_v=True, only_summary=False, force_raw=False, use_cellpy_stat_file=None, cell_type=None, selector=None, **kwargs)[source]

Loads data for given cells.

Parameters

  • raw_files (list) – name of res-files

  • cellpy_file (path) – name of cellpy-file

  • mass (float) – mass of electrode or active material

  • summary_on_raw (bool) – use raw-file for summary

  • summary_ir (bool) – summarize ir

  • summary_ocv (bool) – summarize ocv steps

  • summary_end_v (bool) – summarize end voltage

  • only_summary (bool) – get only the summary of the runs

  • force_raw (bool) – only use raw-files

  • use_cellpy_stat_file (bool) – use stat file if creating summary from raw

  • cell_type (str) – set the cell type (e.g. “anode”). If not, the default from the config file is used.

  • selector (dict) – passed to load.

  • **kwargs – passed to from_raw

Example

>>> srnos = my_dbreader.select_batch("testing_new_solvent")
>>> cell_datas = []
>>> for srno in srnos:
>>> ... my_run_name = my_dbreader.get_cell_name(srno)
>>> ... mass = my_dbreader.get_mass(srno)
>>> ... rawfiles, cellpyfiles =             >>> ...     filefinder.search_for_files(my_run_name)
>>> ... cell_data = cellreader.CellpyData()
>>> ... cell_data.loadcell(raw_files=rawfiles,
>>> ...                    cellpy_file=cellpyfiles)
>>> ... cell_data.set_mass(mass)
>>> ... if not cell_data.summary_exists:
>>> ...     cell_data.make_summary() # etc. etc.
>>> ... cell_datas.append(cell_data)
>>>
make_step_table(step_specifications=None, short=False, profiling=False, all_steps=False, add_c_rate=True, skip_steps=None, sort_rows=True, dataset_number=None, from_data_point=None)[source]

Create a table (v.4) that contains summary information for each step.

This function creates a table containing information about the different steps for each cycle and, based on that, decides what type of step it is (e.g. charge) for each cycle.

The format of the steps is:

index: cycleno - stepno - sub-step-no - ustep Time info (average, stdev, max, min, start, end, delta) - Logging info (average, stdev, max, min, start, end, delta) - Current info (average, stdev, max, min, start, end, delta) - Voltage info (average, stdev, max, min, start, end, delta) - Type (from pre-defined list) - SubType - Info

Args:

step_specifications (pandas.DataFrame): step specifications short (bool): step specifications in short format profiling (bool): turn on profiling

all_steps (bool): investigate all steps including same steps within

one cycle (this is useful for e.g. GITT).

add_c_rate (bool): include a C-rate estimate in the steps skip_steps (list of integers): list of step numbers that should not

be processed (future feature - not used yet).

sort_rows (bool): sort the rows after processing. dataset_number: defaults to self.dataset_number from_data_point (int): first data point to use

Returns

None

make_summary(find_ocv=False, find_ir=False, find_end_voltage=True, use_cellpy_stat_file=None, all_tests=True, dataset_number=0, ensure_step_table=True, add_normalized_cycle_index=True, add_c_rate=True, normalization_cycles=None, nom_cap=None, from_cycle=None)[source]

Convenience function that makes a summary of the cycling data.

merge(datasets=None, separate_datasets=False, **kwargs)[source]

This function merges datasets into one set.

old_load(cellpy_file, parent_level=None, return_cls=True, accept_old=False)[source]

Loads a cellpy file.

Parameters

  • cellpy_file (path, str) – Full path to the cellpy file.

  • parent_level (str, optional) – Parent level. Warning! Deprecating this soon!

  • return_cls (bool) – Return the class.

  • accept_old (bool) – Accept loading old cellpy-file versions. Instead of raising WrongFileVersion it only issues a warning.

Returns

cellpy.CellPyData class if return_cls is True

partial_load(**kwargs)[source]

Load only a selected part of the cellpy file.

populate_step_dict(step, dataset_number=None)[source]

Returns a dict with cycle numbers as keys and corresponding steps (list) as values.

print_steps(dataset_number=None)[source]

Print the step table.

property raw_units
register_instrument_readers()[source]
save(filename, dataset_number=None, force=False, overwrite=None, extension='h5', ensure_step_table=None)[source]

Save the data structure to cellpy-format.

Parameters

  • filename – (str or pathlib.Path) the name you want to give the file

  • dataset_number – (int) if you have several datasets, chose the one you want (probably leave this untouched)

  • force – (bool) save a file even if the summary is not made yet (not recommended)

  • overwrite – (bool) save the new version of the file even if old one exists.

  • extension – (str) filename extension.

  • ensure_step_table – (bool) make step-table if missing.

Returns: Nothing at all.

select_steps(step_dict, append_df=False, dataset_number=None)[source]

Select steps (not documented yet).

set_cellnumber(dataset_number)[source]

Set the cell number.

Set the cell number that will be used (CellpyData.selected_dataset_number). The class can save several datasets (but its not a frequently used feature), the datasets are stored in a list and dataset_number is the selected index in the list.

Several options are available:
n - int in range 0..(len-1) (python uses offset as index, i.e.

starts with 0)

last, end, newest - last (index set to -1) first, zero, beginning, default - first (index set to 0)

set_cellpy_datadir(directory=None)[source]

Set the directory containing .hdf5-files.

Used for setting directory for looking for hdf5-files. A valid directory name is required.

Parameters

directory (str) – path to hdf5-directory

Example

>>> d = CellpyData()
>>> directory = "MyData/HDF5"
>>> d.set_raw_datadir(directory)
static set_col_first(df, col_names)[source]

set selected columns first in a pandas.DataFrame.

This function sets cols with names given in col_names (a list) first in the DataFrame. The last col in col_name will come first (processed last)

set_dataset_number_force(dataset_number=0)[source]

Force to set testnumber.

Sets the DataSet number default (all functions with prm dataset_number will then be run assuming the default set dataset_number)

set_instrument(instrument=None, model=None, instrument_file=None, **kwargs)[source]

Set the instrument (i.e. tell cellpy the file-type you use).

Three different modes of setting instruments are currently supported. You can provide the already supported instrument names (see the documentation, e.g. “arbin_res”). You can use the “custom” loader by providing the path to a yaml-file describing the file format. This can be done either by setting instrument to “instrument_name::instrument_definition_file_name”, or by setting instrument to “custom” and provide the definition file name through the instrument_file keyword argument. A last option exists where you provide the yaml-file name directly to the instrument parameter. Cellpy will then look into your local instrument folder and search for the yaml-file. Some instrument types also supports a model key-word.

Parameters

  • instrument – (str) in [“arbin_res”, “maccor_txt”,…]. If instrument ends with “.yml” a local instrument file will be used. For example, if instrument is “my_instrument.yml”, cellpy will look into the local instruments folders for a file called “my_instrument.yml” and then use LocalTxtLoader to load after registering the instrument. If the instrument name contains a ‘::’ separator, the part after the separator will be interpreted as ‘instrument_file’.

  • model – (str) optionally specify if the instrument loader supports handling several models (some instruments allow for exporting data in slightly different formats depending on the choices made during the export or the model of the instrument, e.g. different number of header lines, different encoding).

  • instrument_file – (path) instrument definition file,

  • kwargs (dict) – key-word arguments sent to the initializer of the loader class

Notes

If you are using a local instrument loader, you will have to register it first to the loader factory. >>> c = CellpyData() # this will automatically register the already implemented loaders >>> c.instrument_factory.register_builder(instrument_id, (module_name, path_to_instrument_loader_file))

It is highly recommended using the module_name as the instrument_id.

set_mass(masses, dataset_number=None, validated=None)[source]

Sets the mass (masses) for the test (datasets).

set_nom_cap(nom_caps, dataset_number=None, validated=None)[source]

Sets the mass (masses) for the test (datasets).

set_raw_datadir(directory=None)[source]

Set the directory containing .res-files.

Used for setting directory for looking for res-files.@ A valid directory name is required.

Parameters

directory (str) – path to res-directory

Example

>>> d = CellpyData()
>>> directory = "MyData/Arbindata"
>>> d.set_raw_datadir(directory)
set_tot_mass(masses, dataset_number=None, validated=None)[source]

Sets the mass (masses) for the test (datasets).

sget_current(cycle, step, dataset_number=None)[source]

Returns current for cycle, step.

Convenience function; same as issuing
raw[(raw[cycle_index_header] == cycle) &

(raw[step_index_header] == step)][current_header]

Parameters

  • cycle – cycle number

  • step – step number

  • dataset_number – the dataset number (automatic selection if None)

Returns

pandas.Series or None if empty

sget_step_numbers(cycle, step, dataset_number=None)[source]

Returns step number for cycle, step.

Convenience function; same as issuing
raw[(raw[cycle_index_header] == cycle) &

(raw[step_index_header] == step)][step_index_header]

Parameters

  • cycle – cycle number

  • step – step number (can be a list of several step numbers)

  • dataset_number – the dataset number (automatic selection if None)

Returns

pandas.Series

sget_steptime(cycle, step, dataset_number=None)[source]

Returns step time for cycle, step.

Convenience function; same as issuing
raw[(raw[cycle_index_header] == cycle) &

(raw[step_index_header] == step)][step_time_header]

Parameters

  • cycle – cycle number

  • step – step number

  • dataset_number – the dataset number (automatic selection if None)

Returns

pandas.Series or None if empty

sget_timestamp(cycle, step, dataset_number=None)[source]

Returns timestamp for cycle, step.

Convenience function; same as issuing
raw[(raw[cycle_index_header] == cycle) &

(raw[step_index_header] == step)][timestamp_header]

Parameters

  • cycle – cycle number

  • step – step number (can be a list of several step numbers)

  • dataset_number – the dataset number (automatic selection if None)

Returns

pandas.Series

sget_voltage(cycle, step, dataset_number=None)[source]

Returns voltage for cycle, step.

Convenience function; same as issuing
raw[(raw[cycle_index_header] == cycle) &

(raw[step_index_header] == step)][voltage_header]

Parameters

  • cycle – cycle number

  • step – step number

  • dataset_number – the dataset number (automatic selection if None)

Returns

pandas.Series or None if empty

split(cycle=None)[source]

Split experiment (CellpyData object) into two sub-experiments. if cycle is not give, it will split on the median cycle number

split_many(base_cycles=None)[source]

Split experiment (CellpyData object) into several sub-experiments.

Parameters

base_cycles (int or list of ints) – cycle(s) to do the split on.

Returns

List of CellpyData objects

to_csv(datadir=None, sep=None, cycles=False, raw=True, summary=True, shifted=False, method=None, shift=0.0, last_cycle=None)[source]

Saves the data as .csv file(s).

Parameters

  • datadir – folder where to save the data (uses current folder if not given).

  • sep – the separator to use in the csv file (defaults to CellpyData.sep).

  • cycles – (bool) export voltage-capacity curves if True.

  • raw – (bool) export raw-data if True.

  • summary – (bool) export summary if True.

  • shifted (bool) – export with cumulated shift.

  • method (string) –

    how the curves are given “back-and-forth” - standard back and forth; discharge

    (or charge) reversed from where charge (or discharge) ends.

    ”forth” - discharge (or charge) continues along x-axis. “forth-and-forth” - discharge (or charge) also starts at 0 (or

    shift if not shift=0.0)

  • shift – start-value for charge (or discharge)

  • last_cycle – process only up to this cycle (if not None).

Returns: Nothing

classmethod vacant(cell=None)[source]

Create a CellpyData instance. :param cell: the attributes from the cell will be copied

to the new Cellpydata instance.

cellpy.readers.cellreader.check_cellpy_file()[source]
cellpy.readers.cellreader.check_raw()[source]
cellpy.readers.cellreader.get(filename=None, mass=None, instrument=None, instrument_file=None, nominal_capacity=None, logging_mode=None, cycle_mode=None, auto_summary=True, testing=False, **kwargs)[source]

Create a CellpyData object

Parameters

  • filename (str, os.PathLike, or list of raw-file names) – path to file(s)

  • mass (float) – mass of active material (mg) (defaults to mass given in cellpy-file or 1.0)

  • instrument (str) – instrument to use (defaults to the one in your cellpy config file)

  • instrument_file (str or path) – yaml file for custom file type

  • nominal_capacity (float) – nominal capacity for the cell (e.g. used for finding C-rates)

  • logging_mode (str) – “INFO” or “DEBUG”

  • cycle_mode (str) – the cycle mode (e.g. “anode” or “full_cell”)

  • auto_summary (bool) – (re-) create summary.

  • testing (bool) – set to True if testing (will for example prevent making .log files)

  • **kwargs – sent to the loader

Returns

CellpyData object (if successful, None if not)

cellpy.readers.core module

This module contains several of the most important classes used in cellpy.

It also contains functions that are used by readers and utils. And it has the file- version definitions.

class cellpy.readers.core.Cell(**kwargs)[source]

Bases: object

Object to store data for a test.

This class is used for storing all the relevant data for a ‘run’, i.e. all the data collected by the tester as stored in the raw-files.

test_no

test number.

Type

int

mass

mass of electrode [mg].

Type

float

dfdata

contains the experimental data points.

Type

pandas.DataFrame

dfsummary

contains summary of the data pr. cycle.

Type

pandas.DataFrame

step_table

information for each step, used for defining type of step (charge, discharge, etc.)

Type

pandas.DataFrame

property has_data
property has_steps

check if the step table exists

property has_summary

check if the summary table exists

class cellpy.readers.core.FileID(filename=None)[source]

Bases: object

class for storing information about the raw-data files.

This class is used for storing and handling raw-data file information. It is important to keep track of when the data was extracted from the raw-data files so that it is easy to know if the hdf5-files used for @storing “treated” data is up-to-date.

name

Filename of the raw-data file.

Type

str

full_name

Filename including path of the raw-data file.

Type

str

size

Size of the raw-data file.

Type

float

last_modified

Last time of modification of the raw-data file.

Type

datetime

last_accessed

last time of access of the raw-data file.

Type

datetime

last_info_changed

st_ctime of the raw-data file.

Type

datetime

location

Location of the raw-data file.

Type

str

get_last()[source]

Get last modification time of the file.

get_name()[source]

Get the filename.

get_raw()[source]

Get a list with information about the file.

The returned list contains name, size, last_modified and location.

get_size()[source]

Get the size of the file.

property last_data_point
populate(filename)[source]

Finds the file-stats and populates the class with stat values.

Parameters

filename (str) – name of the file.

class cellpy.readers.core.InstrumentFactory[source]

Bases: object

create(key: str, **kwargs)[source]

Create the instrument loader module and initialize the loader class.

Parameters

  • key – instrument id

  • **kwargs – sent to the initializer of the loader class.

Returns

instance of loader class.

query(key: str, variable: str) → Any[source]

performs a get_params lookup for the instrument loader.

Parameters

  • key – instrument id.

  • variable – the variable you want to lookup.

Returns

The value of the variable if the loaders get_params method supports it.

register_builder(key: str, builder: Tuple[str, Any], **kwargs) → None[source]

register an instrument loader module.

Parameters

  • key – instrument id

  • builder – (module_name, module_path)

  • **kwargs – stored in the factory (will be used in the future for allowing to set defaults to the builders to allow for using .query).

class cellpy.readers.core.PickleProtocol(level)[source]

Bases: object

cellpy.readers.core.check64bit(current_system='python')[source]

checks if you are on a 64 bit platform

cellpy.readers.core.collect_capacity_curves(data, direction='charge', trim_taper_steps=None, steps_to_skip=None, steptable=None, max_cycle_number=None, **kwargs)[source]

Create a list of pandas.DataFrames, one for each charge step.

The DataFrames are named by its cycle number.

Input: CellpyData Returns: list of pandas.DataFrames,

list of cycle numbers, minimum voltage value, maximum voltage value

cellpy.readers.core.collect_ocv_curves()[source]
cellpy.readers.core.convert_to_mAhg(c, mass=1.0)[source]

Converts capacity in Ah to capacity in mAh/g.

Parameters

  • c (float or numpy array) – capacity in mA.

  • mass (float) – mass in mg.

Returns

1000000 * c / mass

Return type

float

cellpy.readers.core.find_all_instruments() → Dict[str, Tuple[str, str]][source]

finds all the supported instruments

cellpy.readers.core.generate_default_factory()[source]
cellpy.readers.core.group_by_interpolate(df, x=None, y=None, group_by=None, number_of_points=100, tidy=False, individual_x_cols=False, header_name='Unit', dx=10.0, generate_new_x=True)[source]

Do a pandas.DataFrame.group_by and perform interpolation for all groups.

This function is a wrapper around an internal interpolation function in cellpy (that uses scipy.interpolate.interp1d) that combines doing a group-by operation and interpolation.

Parameters

  • df (pandas.DataFrame) – the dataframe to morph.

  • x (str) – the header for the x-value (defaults to normal header step_time_txt) (remark that the default group_by column is the cycle column, and each cycle normally consist of several steps (so you risk interpolating / merging several curves on top of each other (not good)).

  • y (str) – the header for the y-value (defaults to normal header voltage_txt).

  • group_by (str) – the header to group by (defaults to normal header cycle_index_txt)

  • number_of_points (int) – if generating new x-column, how many values it should contain.

  • tidy (bool) – return the result in tidy (i.e. long) format.

  • individual_x_cols (bool) – return as xy xy xy … data.

  • header_name (str) – name for the second level of the columns (only applies for xy xy xy … data) (defaults to “Unit”).

  • dx (float) – if generating new x-column and number_of_points is None or zero, distance between the generated values.

  • generate_new_x (bool) –

    create a new x-column by using the x-min and x-max values from the original dataframe where the method is set by the number_of_points key-word:

    1. if number_of_points is not None (default is 100):

      ` new_x = np.linspace(x_max, x_min, number_of_points) `

    2. else: ` new_x = np.arange(x_max, x_min, dx) `

Returns: pandas.DataFrame with interpolated x- and y-values. The returned

dataframe is in tidy (long) format for tidy=True.

cellpy.readers.core.humanize_bytes(b, precision=1)[source]

Return a humanized string representation of a number of b.

cellpy.readers.core.identify_last_data_point(data)[source]

Find the last data point and store it in the fid instance

cellpy.readers.core.interpolate_y_on_x(df, x=None, y=None, new_x=None, dx=10.0, number_of_points=None, direction=1, **kwargs)[source]

Interpolate a column based on another column.

Parameters

  • df – DataFrame with the (cycle) data.

  • x – Column name for the x-value (defaults to the step-time column).

  • y – Column name for the y-value (defaults to the voltage column).

  • new_x (numpy array or None) – Interpolate using these new x-values instead of generating x-values based on dx or number_of_points.

  • dx – step-value (defaults to 10.0)

  • number_of_points – number of points for interpolated values (use instead of dx and overrides dx if given).

  • direction (-1,1) – if direction is negative, then invert the x-values before interpolating.

  • **kwargs – arguments passed to scipy.interpolate.interp1d

Returns: DataFrame with interpolated y-values based on given or

generated x-values.

cellpy.readers.core.pickle_protocol(level)[source]
cellpy.readers.core.xldate_as_datetime(xldate, datemode=0, option='to_datetime')[source]

Converts a xls date stamp to a more sensible format.

Parameters

  • xldate (str) – date stamp in Excel format.

  • datemode (int) – 0 for 1900-based, 1 for 1904-based.

  • option (str) – option in (“to_datetime”, “to_float”, “to_string”), return value

Returns

datetime (datetime object, float, or string).

cellpy.readers.dbreader module

class cellpy.readers.dbreader.DbSheetCols(level=0)[source]

Bases: object

class cellpy.readers.dbreader.Reader(db_file=None, db_datadir=None, db_datadir_processed=None, db_frame=None)[source]

Bases: object

extract_date_from_cell_name(force=False)[source]
filter_by_col(column_names)[source]

filters sheet/table by columns (input is column header)

The routine returns the serial numbers with values>1 in the selected columns.

Parameters

column_names (list) – the column headers.

Returns

pandas.DataFrame

filter_by_col_value(column_name, min_val=None, max_val=None)[source]

filters sheet/table by column.

The routine returns the serial-numbers with min_val <= values >= max_val in the selected column.

Parameters

  • column_name (str) – column name.

  • min_val (int) – minimum value of serial number.

  • max_val (int) – maximum value of serial number.

Returns

pandas.DataFrame

filter_by_slurry(slurry, appender='_')[source]

Filters sheet/table by slurry name.

Input is slurry name or list of slurry names, for example ‘es030’ or [“es012”,”es033”,”es031”].

Parameters

  • slurry (str or list of strings) – slurry names.

  • appender (chr) – char that surrounds slurry names.

Returns

List of serial_number (ints).

filter_selected(serial_numbers)[source]
get_all()[source]
get_areal_loading(serial_number)[source]
get_args(serial_number: int) → dict[source]
get_by_column_label(column_name, serial_number)[source]
get_cell_name(serial_number)[source]
get_cell_type(serial_number)[source]
get_comment(serial_number)[source]
get_experiment_type(serial_number)[source]
get_fileid(serial_number, full_path=True)[source]
get_group(serial_number)[source]
get_instrument(serial_number)[source]
get_label(serial_number)[source]
get_loading(serial_number)[source]
get_mass(serial_number)[source]
get_nom_cap(serial_number)[source]
get_total_mass(serial_number)[source]
inspect_exists(serial_number)[source]
inspect_hd5f_fixed(serial_number)[source]
static intersect(lists)[source]
pick_table()[source]

Pick the table and return a pandas.DataFrame.

print_serial_number_info(serial_number, print_to_screen=True)[source]

Print information about the run.

Parameters

  • serial_number – serial number.

  • print_to_screen – runs the print statement if True, returns txt if not.

Returns

txt if print_to_screen is False, else None.

select_all(serial_numbers)[source]

Select rows for identification for a list of serial_number.

Parameters

serial_numbers – list (or ndarray) of serial numbers

Returns

pandas.DataFrame

select_batch(batch, batch_col_name=None, case_sensitive=True)[source]

selects the rows in column batch_col_number (default: DbSheetCols.batch)

select_serial_number_row(serial_number)[source]

Select row for identification number serial_number

Parameters

serial_number – serial number

Returns

pandas.DataFrame

static subtract(list1, list2)[source]
static subtract_many(list1, lists)[source]
static union(lists)[source]

cellpy.readers.filefinder module

cellpy.readers.filefinder.create_full_names(run_name, cellpy_file_extension=None, raw_file_dir=None, cellpy_file_dir=None)[source]
cellpy.readers.filefinder.search_for_files(run_name, raw_extension=None, cellpy_file_extension=None, raw_file_dir=None, cellpy_file_dir=None, prm_filename=None, file_name_format=None, reg_exp=None, sub_folders=False, file_list=None, pre_path=None)[source]

Searches for files (raw-data files and cellpy-files).

Parameters

  • run_name (str) – run-file identification.

  • raw_extension (str) – optional, extension of run-files (without the ‘.’).

  • cellpy_file_extension (str) – optional, extension for cellpy files (without the ‘.’).

  • raw_file_dir (path) – optional, directory where to look for run-files (default: read prm-file)

  • cellpy_file_dir (path) – optional, directory where to look for cellpy-files (default: read prm-file)

  • prm_filename (path) – optional parameter file can be given.

  • file_name_format (str) – format of raw-file names or a glob pattern (default: YYYYMMDD_[name]EEE_CC_TT_RR).

  • reg_exp (str) – use regular expression instead (defaults to None).

  • sub_folders (bool) – perform search also in sub-folders.

  • file_list (list of str) – perform the search within a given list of filenames instead of searching the folder(s). The list should not contain the full filepath (only the actual file names). If you want to provide the full path, you will have to modify the file_name_format or reg_exp accordingly.

  • pre_path (path or str) – path to prepend the list of files selected from the file_list.

Returns

run-file names (list) and cellpy-file-name (path).

Module contents