cellpy.utils package

Subpackages

Submodules

cellpy.utils.batch module

Routines for batch processing of cells (v2).

class cellpy.utils.batch.Batch(*args, **kwargs)[source]

Bases: object

A convenient class for running batch procedures.

property cell_names: list
property cell_raw_headers: Index
property cell_step_headers: Index
property cell_summary_headers: Index
property cells: Data

access cells as a Data object (attribute lookup and automatic loading)

combine_summaries(export_to_csv=True, **kwargs) → None[source]

Combine selected columns from each of the cells into single frames

create_folder_structure() → None[source]
create_journal(description=None, from_db=True, **kwargs)[source]

Create journal pages.

This method is a wrapper for the different Journal methods for making journal pages (Batch.experiment.journal.xxx). It is under development. If you want to use ‘advanced’ options (i.e. not loading from a db), please consider using the methods available in Journal for now.

Args:
description: the information and meta-data needed to generate the journal pages (‘empty’: create an

empty journal; dict: create journal pages from a dictionary; pd.DataFrame: create journal pages from a pandas.DataFrame: ‘filename.json’: load cellpy batch file; ‘filename.xlsx’: create journal pages from an Excel file).

from_db (bool): Deprecation Warning: this parameter will be removed as it is

the default anyway. Generate the pages from a db (the default option). This will be over-ridden if description is given.

**kwargs: sent to sub-function(s) (e.g. from_db -> simple_db_reader -> find_files ->

filefinder.search_for_files).

kwargs -> from_db:

project=None, name=None, batch_col=None

kwargs -> simple_db_reader:

reader: a reader object (defaults to dbreader.Reader) cell_ids: keys (cell IDs) file_list: file list to send to filefinder (instead of searching in folders for files). pre_path: prepended path to send to filefinder. include_key: include the key col in the pages (the cell IDs). include_individual_arguments: include the argument column in the pages. additional_column_names: list of additional column names to include in the pages.

kwargs -> filefinder.search_for_files:

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

info_dict

drop(cell_label=None)[source]

Drop cells from the journal.

If cell_label is not given, cellpy will look into the journal for session info about bad cells, and if it finds it, it will remove those from the journal.

Note! remember to save your journal again after modifying it.

Note! this method has not been properly tested yet.

Parameters

cell_label (str) – the cell label of the cell you would like to remove.

Returns

cellpy.utils.batch object (returns a copy if keep_old is True).

duplicate_cellpy_files(location: str = 'standard', selector: Optional[dict] = None, **kwargs) → None[source]

Copy the cellpy files and make a journal with the new names available in the current folder.

Parameters

  • location – where to copy the files. Either choose among the following options: “standard”: data/interim folder “here”: current directory “cellpydatadir”: the stated cellpy data dir in your settings (prms)

  • above (or if the location is not one of the) – location argument.

  • the (use the actual value of) – location argument.

  • selector (dict) – if given, the cellpy files are reloaded after duplicating and modified based on the given selector(s).

  • kwargs – sent to update if selector is provided

Returns

The updated journal pages.

duplicate_journal(folder=None) → None[source]

Copy the journal to folder.

Parameters

  • folder (str or pathlib.Path) – folder to copy to (defaults to the

  • folder). (current) –

export_cellpy_files(path=None, **kwargs) → None[source]
export_journal(filename=None) → None[source]

Export the journal to xlsx.

property info_file
property journal: LabJournal
property journal_name
property labels

Link journal content to the cellpy-files and load the step information.

Parameters

  • max_cycle (int) – set maximum cycle number to link to.

  • force_combine_summaries (bool) – automatically run combine_summaries (set this to True if you are re-linking without max_cycle for a batch that previously were linked with max_cycle)

load() → None[source]
make_summaries() → None[source]
property name
property pages: DataFrame
paginate() → None[source]

Create the folders where cellpy will put its output.

plot_summaries(output_filename=None, backend=None, reload_data=False, **kwargs) → None[source]

Plot the summaries

recalc(**kwargs) → None[source]
report(stylize=True)[source]

Create a report on all the cells in the batch object.

Remark! To perform a reporting, cellpy needs to access all the data (and it might take some time).

Returns

pandas.DataFrame

save_journal() → None[source]

Save the journal (json-format).

The journal file will be saved in the project directory and in the batch-file-directory (prms.Paths.batchfiledir). The latter is useful for processing several batches using the iterate_batches functionality.

show_pages(number_of_rows=5)[source]
property summaries

Concatenated summaries from all cells (multiindex dataframe).

property summary_headers

The column names of the concatenated summaries

update(**kwargs) → None[source]

Updates the selected datasets.

Parameters

  • all_in_memory (bool) – store the cellpydata in memory (default False)

  • cell_specs (dict of dicts) – individual arguments pr. cell. The cellspecs key-word argument dictionary will override the **kwargs and the parameters from the journal pages for the indicated cell.

kwargs:

transferred all the way to the instrument loader, if not picked up earlier. Remark that you can obtain the same pr. cell by providing a cellspecs dictionary. The kwargs have precedence over the parameters given in the journal pages, but will be overridden by parameters given by cellspecs.

Merging:
recalc (Bool): set to False if you don’t want automatic “recalc” of

cycle numbers etc. when merging several data-sets.

Loading:

selector (dict): selector-based parameters sent to the cellpy-file loader (hdf5) if loading from raw is not necessary (or turned off).

property view
cellpy.utils.batch.from_journal(journal_file, autolink=True) → Batch[source]

Create a Batch from a journal file

cellpy.utils.batch.init(*args, **kwargs) → Batch[source]

Returns an initialized instance of the Batch class.

Parameters

  • *args – passed directly to Batch() name: name of batch; project: name of project; batch_col: batch column identifier.

  • **kwargs – file_name: json file if loading from pages; default_log_level: “INFO” or “DEBUG”; the rest is passed directly to Batch().

Examples

>>> empty_batch = Batch.init(db_reader=None)
>>> batch_from_file = Batch.init(file_name="cellpy_batch_my_experiment.json")
>>> normal_init_of_batch = Batch.init()
cellpy.utils.batch.iterate_batches(folder, extension='.json', glob_pattern=None, **kwargs)[source]

Iterate through all journals in given folder.

Parameters

  • folder (str or pathlib.Path) – folder containing the journal files.

  • extension (str) – extension for the journal files (used when creating a default glob-pattern).

  • glob_pattern (str) – optional glob pattern.

  • **kwargs – keyword arguments passed to batch.process_batch.

cellpy.utils.batch.load_pages(file_name) → DataFrame[source]

Retrieve pages from a Journal file.

This function is here to let you easily inspect a Journal file without starting up the full batch-functionality.

Examples

>>> from cellpy.utils import batch
>>> journal_file_name = 'cellpy_journal_one.json'
>>> pages = batch.load_pages(journal_file_name)
Returns

pandas.DataFrame

cellpy.utils.batch.process_batch(*args, **kwargs) → Batch[source]

Execute a batch run, either from a given file_name or by giving the name and project as input.

Examples

>>> process_batch(file_name | (name, project), **kwargs)
Parameters

*args – file_name or name and project (both string)

Keyword Arguments

  • backend (str) – what backend to use when plotting (‘bokeh’ or ‘matplotlib’). Defaults to ‘matplotlib’.

  • dpi (int) – resolution used when saving matplotlib plot(s). Defaults to 300 dpi.

  • default_log_level (str) – What log-level to use for console output. Chose between ‘CRITICAL’, ‘DEBUG’, or ‘INFO’. The default is ‘CRITICAL’ (i.e. usually no log output to console).

Returns

cellpy.batch.Batch object

cellpy.utils.diagnostics module

diagnostics contains routines for creating extracting key features from a set of cells

cellpy.utils.diagnostics.first_cycle_irreversible_capacity()[source]

cellpy.utils.helpers module

cellpy.utils.helpers.add_areal_capacity(cell, cell_id, journal)[source]

Adds areal capacity to the summary.

cellpy.utils.helpers.add_c_rate(cell, nom_cap=None, column_name=None)[source]

Adds C-rates to the step table data frame.

This functionality is now also implemented as default when creating the step_table (make_step_table). However it is kept here if you would like to recalculate the C-rates, for example if you want to use another nominal capacity or if you would like to have more than one column with C-rates.

Parameters

  • cell (CellpyData) – cell object

  • nom_cap (float) – nominal capacity to use for estimating C-rates. Defaults to the nominal capacity defined in the cell object (this is typically set during creation of the CellpyData object based on the value given in the parameter file).

  • column_name (str) – name of the new column. Uses the name defined in cellpy.parameters.internal_settings as default.

Returns

cell object.

cellpy.utils.helpers.add_normalized_capacity(cell, norm_cycles=None, individual_normalization=False, scale=1.0)[source]

Add normalized capacity to the summary.

Parameters

  • cell (CellpyData) – cell to add normalized capacity to.

  • norm_cycles (list of ints) – the cycles that will be used to find the normalization factor from (averaging their capacity)

  • individual_normalization (bool) – find normalization factor for both the charge and the discharge if true, else use normalization factor from charge on both charge and discharge.

  • scale (float) – scale of normalization (default is 1.0).

Returns

cell (CellpyData) with added normalization capacity columns in the summary.

cellpy.utils.helpers.add_normalized_cycle_index(summary, nom_cap=None, column_name=None)[source]

Adds normalized cycles to the summary data frame.

This functionality is now also implemented as default when creating the summary (make_summary). However it is kept here if you would like to redo the normalization, for example if you want to use another nominal capacity or if you would like to have more than one normalized cycle index.

Parameters

  • summary (pandas.DataFrame) – cell summary

  • cell (CellpyData) – cell object

  • nom_cap (float) – nominal capacity to use when normalizing. Defaults to the nominal capacity defined in the cell object (this is typically set during creation of the CellpyData object based on the value given in the parameter file).

  • column_name (str) – name of the new column. Uses the name defined in cellpy.parameters.internal_settings as default.

Returns

cell object now with normalized cycle index in its summary.

cellpy.utils.helpers.concatenate_summaries(b, max_cycle=None, rate=None, on='charge', columns=None, column_names=None, normalize_capacity_on=None, scale_by=None, nom_cap=None, normalize_cycles=False, add_areal=False, group_it=False, rate_std=None, rate_column=None, inverse=False, inverted=False, key_index_bounds=[1, -2], melt=False, cell_type_split_position='auto')[source]

Merge all summaries in a batch into a gigantic summary data frame.

TODO: Allow also dictionaries of cell objects. TODO: Allow iterating through batch-objects (for id, name in b.iteritems() or similar)

Parameters

  • b (cellpy.batch object) – the batch with the cells.

  • max_cycle (int) – drop all cycles above this value.

  • rate (float) – filter on rate (C-rate)

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

  • columns (list) – selected column(s) (using cellpy name) [defaults to “charge_capacity”]

  • column_names (list) – selected column(s) (using exact column name)

  • normalize_capacity_on (list) – list of cycle numbers that will be used for setting the basis of the normalization (typically the first few cycles after formation)

  • scale_by (float or str) – scale the normalized data with nominal capacity if “nom_cap”, or given value (defaults to one).

  • nom_cap (float) – nominal capacity of the cell

  • normalize_cycles (bool) – perform a normalisation of the cycle numbers (also called equivalent cycle index)

  • add_areal (bool) – add areal capacity to the summary

  • group_it (bool) – if True, average pr group.

  • rate_std (float) – allow for this inaccuracy when selecting cycles based on rate

  • rate_column (str) – name of the column containing the C-rates.

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

  • inverted (bool) – select cycles that does not have the steps filtered by given C-rate.

  • key_index_bounds (list) – used when creating a common label for the cells by splitting and combining from key_index_bound[0] to key_index_bound[1].

  • melt (bool) – return frame as melted (long format).

  • cell_type_split_position (int | None | "auto") – list item number for creating a cell type identifier after performing a split(“_”) on the cell names (only valid if melt==True). Set to None to not include a cell_type col.

Returns

Multi-index pandas.DataFrame

Notes

The returned DataFrame has the following structure:

  • top-level columns or second col for melted: cell-names (cell_name)

  • second-level columns or first col for melted: summary headers (summary_headers)

  • row-index or third col for melted: cycle number (cycle_index)

  • cell_type on forth col for melted if cell_type_split_position is given

cellpy.utils.helpers.create_rate_column(df, nom_cap, spec_conv_factor, column='current_avr')[source]

Adds a rate column to the dataframe (steps).

cellpy.utils.helpers.load_and_save_resfile(filename, outfile=None, outdir=None, mass=1.0)[source]

Load a raw data file and save it as cellpy-file.

Parameters

  • mass (float) – active material mass [mg].

  • outdir (path) – optional, path to directory for saving the hdf5-file.

  • outfile (str) – optional, name of hdf5-file.

  • filename (str) – name of the resfile.

Returns

name of saved file.

Return type

out_file_name (str)

cellpy.utils.helpers.make_new_cell()[source]

create an empty CellpyData object.

cellpy.utils.helpers.remove_first_cycles_from_summary(s, first=None)[source]

Remove last rows after given cycle number

cellpy.utils.helpers.remove_last_cycles_from_summary(s, last=None)[source]

Remove last rows after given cycle number

cellpy.utils.helpers.remove_outliers_from_summary_on_index(s, indexes=None, remove_last=False)[source]

Remove rows with supplied indexes (where the indexes typically are cycle-indexes).

Parameters

  • s (pandas.DataFrame) – cellpy summary to process

  • indexes (list) – list of indexes

  • remove_last (bool) – remove the last point

Returns

pandas.DataFrame

cellpy.utils.helpers.remove_outliers_from_summary_on_nn_distance(s, distance=0.7, filter_cols=None, freeze_indexes=None)[source]

Remove outliers with missing neighbours.

Parameters

  • s (pandas.DataFrame) – summary frame

  • distance (float) – cut-off (all cycles that have a closest neighbour further apart this number will be removed)

  • filter_cols (list) – list of column headers to perform the filtering on (defaults to charge and discharge capacity)

  • freeze_indexes (list) – list of cycle indexes that should never be removed (defaults to cycle 1)

Returns

filtered summary (pandas.DataFrame)

Returns:

cellpy.utils.helpers.remove_outliers_from_summary_on_value(s, low=0.0, high=7000, filter_cols=None, freeze_indexes=None)[source]

Remove outliers based highest and lowest allowed value

Parameters

  • s (pandas.DataFrame) – summary frame

  • low (float) – low cut-off (all cycles with values below this number will be removed)

  • high (float) – high cut-off (all cycles with values above this number will be removed)

  • filter_cols (list) – list of column headers to perform the filtering on (defaults to charge and discharge capacity)

  • freeze_indexes (list) – list of cycle indexes that should never be removed (defaults to cycle 1)

Returns

filtered summary (pandas.DataFrame)

Returns:

cellpy.utils.helpers.remove_outliers_from_summary_on_window(s, window_size=3, cut=0.1, iterations=1, col_name=None, freeze_indexes=None)[source]

Removes outliers based based on neighbours

cellpy.utils.helpers.remove_outliers_from_summary_on_zscore(s, zscore_limit=4, filter_cols=None, freeze_indexes=None)[source]

Remove outliers based on z-score.

Parameters

  • s (pandas.DataFrame) – summary frame

  • zscore_limit (int) – remove outliers outside this z-score limit

  • filter_cols (list) – list of column headers to perform the filtering on (defaults to charge and discharge capacity)

  • freeze_indexes (list) – list of cycle indexes that should never be removed (defaults to cycle 1)

Returns

filtered summary (pandas.DataFrame)

cellpy.utils.helpers.select_summary_based_on_rate(cell, rate=None, on=None, rate_std=None, rate_column=None, inverse=False, inverted=False, fix_index=True)[source]

Select only cycles charged or discharged with a given rate.

Parameters

  • cell (cellpy.CellpyData) –

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

  • 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 do not have the given C-rate.

  • inverted (bool) – select cycles that do not have the steps filtered by given C-rate.

  • fix_index (bool) – automatically set cycle indexes as the index for the summary dataframe if not already set.

Returns

filtered summary (Pandas.DataFrame).

cellpy.utils.helpers.split_experiment(cell, base_cycles=None)[source]

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

Parameters

  • cell (CellpyData) – original cell

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

Returns

List of CellpyData objects

cellpy.utils.helpers.update_journal_cellpy_data_dir(pages, new_path=None, from_path='PureWindowsPath', to_path='Path')[source]

Update the path in the pages (batch) from one type of OS to another.

I use this function when I switch from my work PC (windows) to my home computer (mac).

Parameters

  • pages – the (batch.experiment.)journal.pages object (pandas.DataFrame)

  • new_path – the base path (uses prms.Paths.cellpydatadir if not given)

  • from_path – type of path to convert from.

  • to_path – type of path to convert to.

Returns

journal.pages (pandas.DataFrame)

cellpy.utils.helpers.yank_after(b, last=None, keep_old=False)[source]

Cut all cycles after a given cycle index number.

Parameters

  • b (batch object) – the batch object to perform the cut on.

  • {cell_name (last (int or dict) – last index}): the last cycle index to keep (if dict: use individual last indexes for each cell).

  • keep_old (bool) – keep the original batch object and return a copy instead.

Returns

batch object if keep_old is True, else None

cellpy.utils.helpers.yank_before(b, first=None, keep_old=False)[source]

Cut all cycles before a given cycle index number.

Parameters

  • b (batch object) – the batch object to perform the cut on.

  • {cell_name (first (int or dict) – first index}): the first cycle index to keep (if dict: use individual first indexes for each cell).

  • keep_old (bool) – keep the original batch object and return a copy instead.

Returns

batch object if keep_old is True, else None

cellpy.utils.helpers.yank_outliers(b, zscore_limit=None, low=0.0, high=7000.0, filter_cols=None, freeze_indexes=None, remove_indexes=None, remove_last=False, iterations=1, zscore_multiplyer=1.3, distance=None, window_size=None, window_cut=0.1, keep_old=False)[source]

Remove outliers from a batch object.

Parameters

  • b (cellpy.utils.batch object) – the batch object to perform filtering one (required).

  • zscore_limit (int) – will filter based on z-score if given.

  • low (float) – low cut-off (all cycles with values below this number will be removed)

  • high (float) – high cut-off (all cycles with values above this number will be removed)

  • filter_cols (str) – what columns to filter on.

  • freeze_indexes (list) – indexes (cycles) that should never be removed.

  • remove_indexes (dict or list) – if dict, look-up on cell label, else a list that will be the same for all

  • remove_last (dict or bool) – if dict, look-up on cell label.

  • iterations (int) – repeat z-score filtering if zscore_limit is given.

  • zscore_multiplyer (int) – multiply zscore_limit with this number between each z-score filtering (should usually be less than 1).

  • distance (float) – nearest neighbour normalised distance required (typically 0.5).

  • window_size (int) – number of cycles to include in the window.

  • window_cut (float) – cut-off.

  • keep_old (bool) – perform filtering of a copy of the batch object (not recommended at the moment since it then loads the full cellpyfile).

Returns

new cellpy.utils.batch object. else: dictionary of removed cycles

Return type

if keep_old

cellpy.utils.example_data

Tools for getting some data to play with

cellpy.utils.example_data.arbin_file(auto_summary=True, testing=False)[source]

load an example data file (arbin).

Parameters

  • auto_summary (bool) – run make_summary automatically (defaults to True)

  • testing (bool) – run in test mode

Returns

cellpy.CellpyData object with the arbin data loaded

cellpy.utils.example_data.arbin_file_path()[source]

Get the path to an example arbin res file

cellpy.utils.example_data.cellpy_file(testing=False)[source]

load an example cellpy file.

Parameters

testing (bool) – run in test mode

Returns

cellpy.CellpyData object with the arbin data loaded

cellpy.utils.example_data.cellpy_file_path()[source]

Get the path to an example cellpy file

cellpy.utils.ica module

ica contains routines for creating and working with incremental capacity analysis data

class cellpy.utils.ica.Converter(capacity=None, voltage=None, points_pr_split=10, max_points=None, voltage_resolution=None, capacity_resolution=None, minimum_splits=3, interpolation_method='linear', increment_method='diff', pre_smoothing=False, smoothing=False, post_smoothing=True, normalize=True, normalizing_factor=None, normalizing_roof=None, savgol_filter_window_divisor_default=50, savgol_filter_window_order=3, voltage_fwhm=0.01, gaussian_order=0, gaussian_mode='reflect', gaussian_cval=0.0, gaussian_truncate=4.0)[source]

Bases: object

Class for dq-dv handling.

Typical usage is to (1) set the data, (2) inspect the data, (3) pre-process the data, (4) perform the dq-dv transform, and finally (5) post-process the data.

A short note about normalization:

  • If normalization is set to False, then no normalization will be done.

  • If normalization is True, and normalization_factor is None, the total capacity of the half cycle will be used for normalization, else the normalization_factor will be used.

  • If normalization is True, and normalization_roof is not None, the capacity divided by normalization_roof will be used for normalization.

increment_data()[source]

Perform the dq-dv transform.

inspect_data(capacity=None, voltage=None, err_est=False, diff_est=False)[source]

Check and inspect the data.

post_process_data(voltage=None, incremental_capacity=None, voltage_step=None)[source]

Perform post-processing (smoothing, normalisation, interpolation) of the data.

pre_process_data()[source]

Perform some pre-processing of the data (i.e. interpolation).

set_data(capacity, voltage=None, capacity_label='q', voltage_label='v')[source]

Set the data.

cellpy.utils.ica.dqdv(voltage, capacity, voltage_resolution=None, capacity_resolution=None, voltage_fwhm=0.01, pre_smoothing=True, diff_smoothing=False, post_smoothing=True, post_normalization=True, interpolation_method=None, gaussian_order=None, gaussian_mode=None, gaussian_cval=None, gaussian_truncate=None, points_pr_split=None, savgol_filter_window_divisor_default=None, savgol_filter_window_order=None, max_points=None, **kwargs)[source]

Convenience functions for creating dq-dv data from given capacity and voltage data.

Parameters

  • voltage – nd.array or pd.Series

  • capacity – nd.array or pd.Series

  • voltage_resolution – used for interpolating voltage data (e.g. 0.005)

  • capacity_resolution – used for interpolating capacity data

  • voltage_fwhm – used for setting the post-processing gaussian sigma

  • pre_smoothing – set to True for pre-smoothing (window)

  • diff_smoothing – set to True for smoothing during differentiation (window)

  • post_smoothing – set to True for post-smoothing (gaussian)

  • post_normalization – set to True for normalizing to capacity

  • interpolation_method – scipy interpolation method

  • gaussian_order – int

  • gaussian_mode – mode

  • gaussian_cval –

  • gaussian_truncate –

  • points_pr_split – only used when investigating data using splits

  • savgol_filter_window_divisor_default – used for window smoothing

  • savgol_filter_window_order – used for window smoothing

  • max_points – restricting to max points in vector (capacity-selected)

Returns

(voltage, dqdv)

cellpy.utils.ica.dqdv_cycle(cycle, splitter=True, **kwargs)[source]

Convenience functions for creating dq-dv data from given capacity and voltage cycle.

Returns the DataFrame with a ‘voltage’ and a ‘incremental_capacity’ column.

Parameters

  • cycle (pandas.DataFrame) – the cycle data (‘voltage’, ‘capacity’, ‘direction’ (1 or -1)).

  • splitter (bool) – insert a np.NaN row between charge and discharge.

Returns

List of step numbers corresponding to the selected steptype. Returns a pandas.DataFrame instead of a list if pdtype is set to True.

Additional key-word arguments are sent to Converter:

Keyword Arguments

  • points_pr_split (int) – only used when investigating data using splits, defaults to 10.

  • max_points – None

  • voltage_resolution (float) – used for interpolating voltage data (e.g. 0.005)

  • capacity_resolution – used for interpolating capacity data

  • minimum_splits (int) – defaults to 3.

  • interpolation_method – scipy interpolation method

  • increment_method (str) – defaults to “diff”

  • pre_smoothing (bool) – set to True for pre-smoothing (window)

  • smoothing (bool) – set to True for smoothing during differentiation (window)

  • post_smoothing (bool) – set to True for post-smoothing (gaussian)

  • normalize (bool) – set to True for normalizing to capacity

  • normalizing_factor (float) –

  • normalizing_roof (float) –

  • savgol_filter_window_divisor_default (int) – used for window smoothing, defaults to 50

  • savgol_filter_window_order – used for window smoothing

  • voltage_fwhm (float) – used for setting the post-processing gaussian sigma, defaults to 0.01

  • gaussian_order (int) – defaults to 0

  • gaussian_mode (str) – defaults to “reflect”

  • gaussian_cval (float) – defaults to 0.0

  • gaussian_truncate (float) – defaults to 4.0

Example

>>> cycle_df = my_data.get_cap(
>>> ...   1,
>>> ...   categorical_column=True,
>>> ...   method = "forth-and-forth"
>>> ...   insert_nan=False,
>>> ... )
>>> voltage, incremental = ica.dqdv_cycle(cycle_df)
cellpy.utils.ica.dqdv_cycles(cycles, not_merged=False, **kwargs)[source]

Convenience functions for creating dq-dv data from given capacity and voltage cycles.

Returns a DataFrame with a ‘voltage’ and a ‘incremental_capacity’ column.

Parameters

  • cycles (pandas.DataFrame) – the cycle data (‘cycle’, ‘voltage’, ‘capacity’, ‘direction’ (1 or -1)).

  • not_merged (bool) – return list of frames instead of concatenating ( defaults to False).

Returns

pandas.DataFrame with columns ‘cycle’, ‘voltage’, ‘dq’.

Additional key-word arguments are sent to Converter:

Keyword Arguments

  • points_pr_split (int) – only used when investigating data using splits, defaults to 10.

  • max_points – None

  • voltage_resolution (float) – used for interpolating voltage data (e.g. 0.005)

  • capacity_resolution – used for interpolating capacity data

  • minimum_splits (int) – defaults to 3.

  • interpolation_method – scipy interpolation method

  • increment_method (str) – defaults to “diff”

  • pre_smoothing (bool) – set to True for pre-smoothing (window)

  • smoothing (bool) – set to True for smoothing during differentiation (window)

  • post_smoothing (bool) – set to True for post-smoothing (gaussian)

  • normalize (bool) – set to True for normalizing to capacity

  • normalizing_factor (float) –

  • normalizing_roof (float) –

  • savgol_filter_window_divisor_default (int) – used for window smoothing, defaults to 50

  • savgol_filter_window_order – used for window smoothing

  • voltage_fwhm (float) – used for setting the post-processing gaussian sigma, defaults to 0.01

  • gaussian_order (int) – defaults to 0

  • gaussian_mode (str) – defaults to “reflect”

  • gaussian_cval (float) – defaults to 0.0

  • gaussian_truncate (float) – defaults to 4.0

Example

>>> cycles_df = my_data.get_cap(
>>> ...   categorical_column=True,
>>> ...   method = "forth-and-forth",
>>> ...   label_cycle_number=True,
>>> ...   insert_nan=False,
>>> ... )
>>> ica_df = ica.dqdv_cycles(cycles_df)
cellpy.utils.ica.dqdv_frames(cell, split=False, tidy=True, **kwargs)[source]

Returns dqdv data as pandas.DataFrame(s) for all cycles.

Parameters

  • cell (CellpyData-object) –

  • split (bool) – return one frame for charge and one for discharge if True (defaults to False).

  • tidy (bool) – returns the split frames in wide format (defaults to True. Remark that this option is currently not available for non-split frames).

Returns

cycle: cycle number (if split is set to True). voltage: voltage dq: the incremental capacity

Return type

one or two pandas.DataFrame with the following columns

Additional key-word arguments are sent to Converter:

Keyword Arguments

  • cycle (int or list of ints (cycle numbers)) – will process all (or up to max_cycle_number) if not given or equal to None.

  • points_pr_split (int) – only used when investigating data using splits, defaults to 10.

  • max_points – None

  • voltage_resolution (float) – used for interpolating voltage data (e.g. 0.005)

  • capacity_resolution – used for interpolating capacity data

  • minimum_splits (int) – defaults to 3.

  • interpolation_method – scipy interpolation method

  • increment_method (str) – defaults to “diff”

  • pre_smoothing (bool) – set to True for pre-smoothing (window)

  • smoothing (bool) – set to True for smoothing during differentiation (window)

  • post_smoothing (bool) – set to True for post-smoothing (gaussian)

  • normalize (bool) – set to True for normalizing to capacity

  • normalizing_factor (float) –

  • normalizing_roof (float) –

  • savgol_filter_window_divisor_default (int) – used for window smoothing, defaults to 50

  • savgol_filter_window_order – used for window smoothing

  • voltage_fwhm (float) – used for setting the post-processing gaussian sigma, defaults to 0.01

  • gaussian_order (int) – defaults to 0

  • gaussian_mode (str) – defaults to “reflect”

  • gaussian_cval (float) – defaults to 0.0

  • gaussian_truncate (float) – defaults to 4.0

Example

>>> from cellpy.utils import ica
>>> charge_df, dcharge_df = ica.ica_frames(my_cell, split=True)
>>> charge_df.plot(x=("voltage", "v"))
cellpy.utils.ica.index_bounds(x)[source]

Returns tuple with first and last item.

cellpy.utils.ica.value_bounds(x)[source]

Returns tuple with min and max in x.

cellpy.utils.live module (not implemented yet)

Routines for streaming cell data

cellpy.utils.ocv_rlx module

class cellpy.utils.ocv_rlx.MultiCycleOcvFit(cellpydata, cycles, circuits=3)[source]

Bases: object

get_best_fit_data()[source]

Returns the best fit data.

get_best_fit_parameters()[source]

Returns parameters for the best fit.

get_best_fit_parameters_grouped()[source]

Returns a dictionary of the best fit.

get_best_fit_parameters_translated()[source]

Returns the parameters in ‘real units’ for the best fit.

get_best_fit_parameters_translated_grouped()[source]

Returns the parameters as a dictionary of the ‘real units’ for the best fit.

get_fit_cycles()[source]

Returns the fit cycles

plot_summary(cycles=None)[source]

Convenience function for plotting the summary of the fit

plot_summary_translated()[source]

Convenience function for plotting the summary of the fit (translated)

run_fitting(direction='up', weighted=True)[source]
Parameters

  • direction ('up' | 'down') – what type of ocv relaxation to fit

  • weighted (bool) – use weighted fitting.

Returns

None

set_cycles(cycles)[source]

Sets the cycles.

set_data(cellpydata)[source]

Sets the CellpyData.

class cellpy.utils.ocv_rlx.OcvFit(zero_current=0.1, zero_voltage=0.05)[source]

Bases: object

Class for fitting open circuit relaxation data.

create_model()[source]
fit_model()[source]
get_best_fit_data()[source]
get_best_fit_parameters()[source]
get_best_fit_parameters_translated()[source]
get_result()[source]
reset_weights()[source]
run_fit()[source]

Performing fit of the OCV steps in the cycles set by set_cycles() from the data set by set_data()

r is found by calculating v0 / i_start –> err(r)= err(v0) + err(i_start).

c is found from using tau / r –> err(c) = err(r) + err(tau).

The resulting best fit parameters are stored in self.result for the given cycles.

Returns

None

set_cellpydata(cellpydata, cycle)[source]

Performing fit of the OCV steps in the cycles set by set_cycles() from the data set by set_data()

r is found by calculating v0 / i_start –> err(r)= err(v0) + err(i_start).

c is found from using tau / r –> err(c) = err(r) + err(tau).

Parameters

  • cellpydata (CellpyData) – data object from cellreader

  • cycle (int) – cycle number to get from CellpyData object

Returns

None

set_circuits(circuits)[source]
set_data(time, voltage)[source]
set_weights(weights)[source]
set_weights_power_law(prefactor=1, power=-2, zero_level=1)[source]
set_zero_current(zero_current)[source]
set_zero_voltage(zero_voltage)[source]
cellpy.utils.ocv_rlx.select_ocv_points(cellpydata, cycles=None, cell_label=None, include_times=True, selection_method='martin', number_of_points=5, interval=10, relative_voltage=False, report_times=False, direction='both')[source]

Select points from the ocvrlx steps.

Parameters

  • cellpydata – CellpyData-object

  • cycles – list of cycle numbers to process (optional)

  • cell_label (str) – optional, will be added to the frame if given

  • include_times (bool) – include additional information including times.

  • selection_method ('martin' | 'fixed_times') – criteria for selecting points (‘martin’: select first and last, and then last/2, last/2/2 etc. until you have reached the wanted number of points; ‘fixed_times’: select first, and then same interval between each subsequent point).

  • number_of_points – number of points you want.

  • interval – interval between each point (in use only for methods where interval makes sense). If it is a list, then number_of_points will be calculated as len(interval) + 1 (and override the set number_of_points).

  • relative_voltage – set to True if you would like the voltage to be relative to the voltage before starting the ocv rlx step. Defaults to False. Remark that for the initial rxl step (when you just have put your cell on the tester) does not have any prior voltage. The relative voltage will then be versus the first measurement point.

  • report_times – also report the ocv rlx total time if True (defaults to False)

  • direction ("up", "down" or "both") – select “up” if you would like to process only the ocv rlx steps where the voltage is relaxing upwards and vice versa. Defaults to “both”.

Returns

pandas.DataFrame (and another pandas.DataFrame if return_times is True)

cellpy.utils.plotutils module

Utilities for helping to plot cellpy-data.

cellpy.utils.plotutils.bplot(b, individual=False, cols=1, **kwargs)[source]

plot batch summaries.

This is wrapper around the two functions concatenate_summaries and plot_concatenated.

>>> p1 = bplot(b, columns=["charge_capacity"], journal=b.experiment.journal, group_it=True)

is equivalent to:

>>> cs = helpers.concatenate_summaries(b, columns=["charge_capacity"], group_it=True)
>>> p1 = plot_concatenated(cs, journal=journal)
Parameters

  • b (cellpy.batch object) – the batch with the cells.

  • individual (bool) – in case of multiple columns, return a list of plots instaed of a hv.Layout

  • cols (int) – number of columns.

Key-word arguments sent further to the concatenator:

Keyword Arguments

  • rate (float) – filter on rate (C-rate)

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

  • columns (list) – selected column(s) (using cellpy name) [defaults to “charge_capacity”]

  • column_names (list) – selected column(s) (using exact column name)

  • normalize_capacity_on (list) – list of cycle numbers that will be used for setting the basis of the normalization (typically the first few cycles after formation)

  • scale_by (float or str) – scale the normalized data with nominal capacity if “nom_cap”, or given value (defaults to one).

  • nom_cap (float) – nominal capacity of the cell

  • normalize_cycles (bool) – perform a normalisation of the cycle numbers (also called equivalent cycle index)

  • add_areal (bool) – add areal capacity to the summary

  • group_it (bool) – if True, average pr group.

  • rate_std (float) – allow for this inaccuracy when selecting cycles based on rate

  • rate_column (str) – name of the column containing the C-rates.

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

  • inverted (bool) – select cycles that do not have the steps filtered by given C-rate.

  • journal (batch.journal object) – the journal (will use the journal in b if not given).

Key-word arguments sent further to the plotter:

Keyword Arguments

  • width (int) – width of plot.

  • spread (bool) – use error-spread instead of error-bars.

  • simple (bool) – use hv.Overlay instead of hv.NdOverlay.

Returns

holoviews plot

cellpy.utils.plotutils.create_colormarkerlist(groups, sub_groups, symbol_label='all', color_style_label='seaborn-colorblind')[source]

Fetch lists with color names and marker types of correct length.

Parameters

  • groups – list of group numbers (used to generate the list of colors)

  • sub_groups – list of sub-group numbers (used to generate the list of markers).

  • symbol_label – sub-set of markers to use

  • color_style_label – cmap to use for colors

Returns

colors (list), markers (list)

cellpy.utils.plotutils.create_colormarkerlist_for_journal(journal, symbol_label='all', color_style_label='seaborn-colorblind')[source]

Fetch lists with color names and marker types of correct length for a journal.

Parameters

  • journal – cellpy journal

  • symbol_label – sub-set of markers to use

  • color_style_label – cmap to use for colors

Returns

colors (list), markers (list)

cellpy.utils.plotutils.cycle_info_plot(cell, cycle=None, step=None, title=None, points=False, x=None, y=None, info_level=1, h_cycle=None, h_step=None, show_it=True, label_cycles=True, label_steps=False, get_axes=False, use_bokeh=True, **kwargs)[source]

Show raw data together with step and cycle information.

Parameters

  • cell – cellpy object

  • cycle – cycles to select (optional, default is all)

  • step – steps to select (optional, defaults is all)

  • title – a title to give the plot

  • points – overlay a scatter plot

  • x (str) – column header for the x-value (defaults to “Test_Time”)

  • y (str) – column header for the y-value (defaults to “Voltage”)

  • info_level (int) – how much information to display (defaults to 1) (0 - almost nothing 1 - pretty much 2 - something else 3 - not implemented yet).

  • h_cycle – column header for the cycle number (defaults to “Cycle_Index”)

  • h_step – column header for the step number (defaults to “Step_Index”)

  • show_it (bool) – show the figure (defaults to True). If not, return the figure.

  • label_cycles (bool) – add labels with cycle numbers.

  • label_steps (bool) – add labels with step numbers

  • get_axes (bool) – return axes (for matplotlib)

  • use_bokeh (bool) – use bokeh to plot (defaults to True). If not, use matplotlib.

  • **kwargs – parameters specific to either matplotlib or bokeh.

Returns

matplotlib.axes or None

cellpy.utils.plotutils.find_column(columns, label=None, end='cycle_index')[source]

find columns based on how the column-name ends.

Parameters

  • columns – pandas columns

  • label – if not provided, generate, if provided, return as is

  • end – the string to use for searching

Returns

column header, label

cellpy.utils.plotutils.hv_bokeh_to_mpl(figure, wide=False, size=(6, 4), **kwargs)[source]
cellpy.utils.plotutils.oplot(b, cap_ylim=None, ce_ylim=None, ir_ylim=None, simple=False, group_it=False, spread=True, capacity_unit='gravimetric', **kwargs)[source]

create a holoviews-plot containing Coulombic Efficiency, Capacity, and IR.

Parameters

  • b (cellpy.batch object) – the batch with the cells.

  • cap_ylim (tuple of two floats) – scaling of y-axis for capacity plots.

  • ce_ylim (tuple of two floats) – scaling of y-axis for c.e. plots.

  • ir_ylim (tuple of two floats) – scaling of y-axis for i.r. plots.

  • simple (bool) – if True, use hv.Overlay instead of hv.NdOverlay.

  • group_it (bool) – if True, average pr group.

  • spread (bool) – if True, show spread instead of error-bars

  • capacity_unit (str) – select “gravimetric”, or “areal”

Returns

hv.Overlay or hv.NdOverlay

cellpy.utils.plotutils.plot_concatenated(dataframe, x=None, y=None, err=None, xlabel=None, ylabel=None, points=True, line=True, errors=True, hover=True, width=800, height=300, journal=None, file_id_level=0, hdr_level=None, axis=1, mean_end='_mean', std_end='_std', cycle_end='cycle_index', legend_title='cell-type', marker_size=None, cmap='default_colors', spread=False, extension='bokeh', edges=False, keys=None, simple=False, **kwargs)[source]

Create a holoviews plot of the concatenated summary.

This function is still under development. Feel free to contribute.

Parameters

  • dataframe – the concatenated summary

  • x – colum-name for the x variable (not implemented yet)

  • y – colum-name for the y variable (not implemented yet)

  • err – colum-name for the std variable (not implemented yet)

  • xlabel – label for x-axis

  • ylabel – label for y-axis

  • points (bool) – plot points if True

  • line (bool) – plot line if True

  • errors (bool) – plot errors if True

  • hover (bool) – add hover tool if True

  • width – width of plot

  • height – height of plot

  • journal – batch.journal object

  • file_id_level – the level (multiindex-level) where the cell-names are.

  • hdr_level – the level (multiindex-level) where the parameter names are.

  • axis – what axis to use when looking in the data-frame (row-based or col-based).

  • mean_end – used for searching for y-column names

  • std_end – used for searching for e-column names

  • cycle_end – used for searching for x-column name

  • legend_title – title to put over the legends

  • marker_size – size of the markers used

  • cmap – color-map to use

  • spread (bool) – plot error-bands instead of error-bars if True

  • extension (str) – “matplotlib” or “bokeh”. Note, this uses hv.extension) and will affect the state of your notebook

  • edges (bool) – show all axes

  • keys (dict) – columns to plot (not working yet)

  • simple (bool) – making a simple hv.Overlay instead of an hv.NdOverlay if True

  • **kwargs – key-word arguments sent to hv.NdOverlay

Example

>>> my_mpl_plot = plot_concatenated(
>>>     cap_cycle_norm_fast_1000, journal=b.experiment.journal,
>>>     height=500, marker_size=5,
>>>     extension="matplotlib",
>>>     edges=True,
>>> )

>>> my_bokeh_plot = plot_concatenated(
>>>     cap_cycle_norm_fast_1000, journal=b.experiment.journal,
>>>     height=500, marker_size=5,
>>>     edges=True,
>>> )

Example

>>> # Simple conversion from bokeh to matplotlib
>>> # NB! make sure you have only used matplotlib-bokeh convertable key-words (not marker_size)

>>> hv.extension("matplotlib")
>>> my_plot.opts(aspect="auto", fig_inches=(12,7), fig_size=90, legend_position="top_right",
>>>              legend_cols = 2,
>>>              show_frame=True)
cellpy.utils.plotutils.raw_plot(cell, y=('voltage', 'Voltage (V vs Li/Li+)'), title=None, **kwargs)[source]
cellpy.utils.plotutils.save_fig(figure, file_name=None, wide=False, size=None, dpi=300, **kwargs)[source]

Save a figure, either a holoviews plot or a matplotlib figure.

This function should mainly be used when using the standard cellpy notebook template (generated by ‘> cellpy new’)

Parameters

  • figure (obj) – the figure or plot object

  • file_name (str) – the file name

  • wide (bool) – release the equal aspect lock (default on for holoviews)

  • size (int or tuple of ints) – figure size in inches

  • dpi (int) – resolution

  • **kwargs – sent to cellpy.utils.plotutils.hv_bokeh_to_mpl

cellpy.utils.easyplot module

easyplot module for cellpy. It provides easy plotting of any cellpy-readable data using matplotlib. Author: Amund M. Raniseth Date: 01.07.2021

class cellpy.utils.easyplot.EasyPlot(files=None, nicknames=None, journal=None, **kwargs)[source]

Bases: object

Main easyplot class. Takes all the inputs from the user in its kwargs upon object initialization. Gathers data, handles and plots it when object.plot() is called.

Help: type easyplot.help()

fill_input()[source]

Fill in the rest of the variables from self.user_params if the user didn’t specify

fix_cap_from_rc(fig, ax, handles)[source]

Makes the finishing touches to the capacity vs inverse C-rate plot

fix_cyclelife(fig, ax)[source]

Makes the finishing touches to the cyclelife plot

fix_dqdv(fig, ax)[source]

Makes the finishing touches to the dQdV plot

fix_gc(fig, ax)[source]

Makes the finishing touches to the voltage-curves plot

fix_gc_and_dqdv(fig, axs)[source]

Makes the finishing touches to the dQdV / Voltage curves plot

give_color()[source]

Picks the first color from the color list and gives it away

give_fig()[source]

Gives figure to whoever asks and appends it to figure list

handle_outpath()[source]

Makes sure that self.outpath exists, or creates it.

plot()[source]

This is the method the user calls on his/hers easyplot object in order to gather the data and plot it. Usage: object.plot()

plot_cap_from_rc()[source]

Takes all the parameters inserted in the object creation and plots capacity VS inverse c-rate

plot_cyclelife()[source]

Takes all the parameters inserted in the object creation and plots cyclelife

plot_dQdV()[source]

Takes all the parameters inserted in the object creation and plots dQdV

plot_gc()[source]

Takes all the parameters inserted in the object creation and plots Voltage-Capacity curves

plot_gc_and_dQdV()[source]

Takes all the parameters inserted in the object creation and plots Voltage-Curves and dQdV data together

save_fig(fig, savepath)[source]

The point of this is to have savefig parameters the same across all plots (for now just fig dpi and bbox inches)

set_arbin_sql_credentials(server='localhost', uid='sa', pwd='Changeme123', driver='ODBC Driver 17 for SQL Server')[source]

Sets cellpy.prms.Instruments.Arbin details to fit what is inserted. Parameters: Server = ‘IP of server’, uid = ‘username’, pwd = ‘password’, driver = ‘ODBC Driver 17 for SQL Server’

verify_input()[source]

Verifies that the users’ input to the object is correct.

cellpy.utils.easyplot.get_effective_C_rates(steptable)[source]
cellpy.utils.easyplot.get_effective_C_rates_and_caps(steptable)[source]
cellpy.utils.easyplot.help()[source]

Method of the EasyPlot class which prints some helptext in addition to all supported params.

cellpy.utils.easyplot.main()[source]

Module contents