cellpy.utils package

cellpy.utils package#

Subpackages#

cellpy.utils.batch_tools package

Submodules#

cellpy.utils.batch module#

Routines for batch processing of cells (v2).

class Batch(*args, **kwargs)[source]#

Bases: object

A convenience class for running batch procedures.

The Batch class contains (among other things):

iterator protocol
a journal with info about the different cells where the main information is accessible as a pandas.DataFrame through the .pages attribute
a data lookup accessor .data that behaves similarly as a dict.

property cell_names: list#

property cell_raw_headers: Index#

property cell_step_headers: Index#

property cell_summary_headers: Index#

collect(cells: list[CellpyCell] = None, **kwargs)[source]#

Collect data from the cells.

Parameters:

cells (list) – list of cellpy cell objects.
**kwargs – keyword arguments to be sent to the collector.

Returns:

None

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

Combine selected columns from each of the cells into single frames.

Keyword Arguments:

export_to_csv (bool) – export the combined summaries to csv (defaults to True).
**kwargs – sent to the summary_collector.

Returns:

None

create_journal(description=None, from_db=True, auto_use_file_list=None, file_list_kwargs=None, abort_on_empty=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.

Parameters:

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.
auto_use_file_list (bool) – Experimental feature. If True, a file list will be generated and used instead of searching for files in the folders.
file_list_kwargs (dict) – Experimental feature. Keyword arguments to be sent to the file list generator.
abort_on_empty (bool) – If True, the function will raise a cellpy.exceptions.NullData if no journal pages are found.
**kwargs – sent to sub-function(s) (e.g. from_db -> simple_db_reader -> find_files -> filefinder.search_for_files).

When using a custom JSON reader (e.g. batbase_json_reader or custom_json_reader), file search is performed after reading the JSON, using the filename/file_name_indicator column as run name. Use file_list and pre_path to control search, or skip_file_search=True to leave existing raw/cellpy paths unchanged.

The following keyword arguments are picked up by from_db:

Transferred Parameters:

project – None
name – None
batch_col – None

The following keyword arguments are picked up by simple_db_reader:

Transferred Parameters:

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.

The following keyword arguments are picked up by filefinder.search_for_files:

Transferred 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)
project_dir (path) – subdirectory in raw_file_dir to look for run-files
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.

The following keyword arguments are picked up by journal.to_file:

Transferred Parameters:: duplicate_to_local_folder (bool) – default True.
Returns:: None

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.

Warning

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

drop_cell(cell_label)[source]#

Drop a cell from the journal.

Parameters:: cell_label – the cell label of the cell you would like to remove.

drop_cells(cell_labels)[source]#

Drop cells from the journal.

Parameters:: cell_labels – the cell labels of the cells you would like to remove.

drop_cells_marked_bad()[source]#: Drop cells that has been marked as bad from the journal (experimental feature).

duplicate_cellpy_files(location: str = 'standard', selector: 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)
or if the location is not one of the above, use the actual value of the location argument.
selector (dict) – if given, the cellpy files are reloaded after duplicating and modified based on the given selector(s).
**kwargs – sent to Batch.experiment.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.

Parameters:: filename (str or pathlib.Path) – the name of the file to save the journal to. If not given, the journal will be saved to the default name.

property info_file#: The name of the info file.

Warning

Will be deprecated soon - use journal_name instead.

property journal: LabJournal#

property journal_name#

property labels#

link(max_cycle: int | None = None, mark_bad=False, force_combine_summaries=False) → None[source]#

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

Parameters:

max_cycle (int) – set maximum cycle number to link to.
mark_bad (bool) – mark cells as bad if they are not linked.
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]#: Load the selected datasets.

Warning

Will be deprecated soon - use update instead.

make_summaries() → None[source]#: Combine selected columns from each of the cells into single frames and export.

Warning

This method will be deprecated in the future. Use combine_summaries instead.

mark_as_bad(cell_label)[source]#

Mark a cell as bad (experimental feature).

Parameters:: cell_label – the cell label of the cell you would like to mark as bad.

property name#

property pages: DataFrame#

paginate() → None[source]#: Create the folders where cellpy will put its output.

plot(backend=None, reload_data=False, **kwargs)[source]#

Plot the summaries (e.g. capacity vs. cycle number).

Parameters:

backend (str) – plotting backend (plotly, bokeh, matplotlib, seaborn)
reload_data (bool) – reload the data before plotting
**kwargs – sent to the plotter

Keyword Arguments:

color_map (str, any) – color map to use (defaults to px.colors.qualitative.Set1 for plotly and “Set1” for seaborn)
ce_range (list) – optional range for the coulombic efficiency plot
min_cycle (int) – minimum cycle number to plot
max_cycle (int) – maximum cycle number to plot
title (str) – title of the figure (defaults to “Cycle Summary”)
x_label (str) – title of the x-label (defaults to “Cycle Number”)
direction (str) – plot charge or discharge (defaults to “charge”)
rate (bool) – (defaults to False)
ir (bool) – (defaults to True)
group_legends (bool) – group the legends so that they can be turned visible/invisible as a group (defaults to True) (only for plotly)
base_template (str) – template to use for the plot (only for plotly)
filter_by_group (int or list of ints) – show only the selected group(s)
filter_by_name (str) – show only cells containing this string
inverted_mode (bool) – invert the colors vs symbols (only for plotly)
only_selected (bool) – only show the selected cells
capacity_specifics (str) – select how to present the capacity (“gravimetric”, “areal” or “absolute”) (defaults to “gravimetric”)

Usage:

b.plot(backend=”plotly”, reload_data=False, color_map=”Set2”, ce_range=[95, 105],: min_cycle=1, max_cycle=100, title=”Cycle Summary”, x_label=”Cycle Number”, direction=”charge”, rate=False, ir=True, group_legends=True, base_template=”plotly_dark”, filter_by_group=1, filter_by_name=”2019”, capacity_specifics=”areal”)

# to get the plotly canvas: my_canvas = b.plotter.figure

plot_summaries(output_filename=None, backend=None, reload_data=False, **kwargs) → None[source]#: Plot the summaries.

Warning

This method will be deprecated in the future. Use plot instead.

recalc(**kwargs) → None[source]#

Run make_step_table and make_summary on all cells.

Keyword Arguments:

save (bool) – Save updated cellpy-files if True (defaults to True).
step_opts (dict) – parameters to inject to make_steps (defaults to None).
summary_opts (dict) – parameters to inject to make_summary (defaults to None).
indexes (list) – Only recalculate for given indexes (i.e. list of cell-names) (defaults to None).
calc_steps (bool) – Run make_steps before making the summary (defaults to True).
testing (bool) – Only for testing purposes (defaults to False).

Examples

>>> # re-make summaries for all cells assuming cell-type is "anode" (anode half-cells):
>>> b.recalc(save=False, calc_steps=False, summary_opts=dict(cell_type="anode"))

Returns:: None

remove_mark_as_bad(cell_label)[source]#

Remove the bad cell mark from a cell (experimental feature).

Parameters:: cell_label – the cell label of the cell you would like to remove the bad mark from.

report(stylize=True, grouped=False, check=False)[source]#

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

Important

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

Parameters:

stylize (bool) – apply some styling to the report (default True).
grouped (bool) – add information based on the group cell belongs to (default False).
check (bool) – check if the data seems to be without errors (0 = no errors, 1 = partial duplicates) (default False).

Returns:

pandas.DataFrame

save() → None[source]#

Save journal and cellpy files.

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

The name and location of the cellpy files is determined by the journal pages.

save_journal(paginate=False, duplicate_to_project_folder=False) → None[source]#

Save the journal (json-format).

The journal file will be saved to the current directory by default. Optionally, it can be copied to the project directory in config.paths.outdatadir and/or the batch-file-directory (config.paths.batchfiledir).

Parameters:

paginate (bool) – paginate the journal pages, i.e. create a project folder structure inside your ‘out’ folder (default False).
duplicate_to_project_folder (bool) – if True, copy the journal to config.paths.outdatadir/project/ (default False).

show_pages(number_of_rows=5)[source]#: Show the journal pages.

Warning

Will be deprecated soon - use pages.head() instead.

property summaries#: Concatenated summaries from all cells (multiindex dataframe).

property summary_headers#: The column names of the concatenated summaries

update(pool=False, **kwargs) → None[source]#

Updates the selected datasets.

Keyword Arguments:

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.
logging_mode (str) – sets the logging mode for the loader(s).
accept_errors (bool) – if True, the loader will continue even if it encounters errors.

Additional keyword arguments are sent to the loader(s) 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 picks up the following keyword arguments:

Transferred Parameters:: recalc (Bool) – set to False if you don’t want automatic recalculation of cycle numbers etc. when merging several data-sets.

Loading picks up the following keyword arguments:

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

property view#: Show the selected info about each cell.

Warning

Will be deprecated soon - use report() instead.

from_journal(journal_file, autolink=True, testing=False, **kwargs) → Batch[source]#: Create a Batch from a journal file

from_journal2(journal_file, autolink=True, testing=False, **kwargs) → Batch[source]#

Create a Batch from a journal file

This function will be renamed to from_journal in the future. It uses the “new” mode of the Batch class.

Parameters:

journal_file – the path to the journal file
autolink – if True, the batch will be linked automatically
testing – should be set to True in test mode
**kwargs – additional keyword arguments - db_reader: the reader to use (defaults to “default”) - testing: if True, the batch will be tested - default_log_level: the default log level (defaults to “CRITICAL”) - custom_log_dir: the directory to save the log file (defaults to None) - reset_big_log: if True, the big log will be reset (defaults to True)

Returns:

Batch object (cellpy.utils.batch.Batch)

Examples

>>> b = batch.from_journal2("cellpy_journal_one.json", testing=True, db_reader="batbase_json_reader")
>>> b.create_journal()
>>> b.update()
>>> b.plot()

init(*args, empty=False, **kwargs) → Batch[source]#

Returns an initialized instance of the Batch class.

Parameters:

empty (bool) – if True, the batch will not be linked to any database and an empty batch is returned
*args –
passed directly to Batch()
- name: name of batch.
- project: name of project.
- batch_col: batch column identifier.

Keyword Arguments:

file_name – json file if loading from pages (journal).
default_log_level – “INFO” or “DEBUG”. Defaults to “CRITICAL”.

Other keyword arguments are sent to the Batch object.

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

init2(*args, empty=False, **kwargs) → Batch[source]#

Returns an initialized instance of the Batch class.

Parameters:

empty (bool) – if True, the batch will not be linked to any database and an empty batch is returned
*args –
passed directly to Batch()
- name: name of batch.
- project: name of project.
- batch_col: batch column identifier.

Keyword Arguments:

file_name – json file if loading from pages (journal).
default_log_level – “INFO” or “DEBUG”. Defaults to “CRITICAL”.

Other keyword arguments are sent to the Batch object.

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

iterate_batches(folder, extension='.json', glob_pattern=None, **kwargs)[source]#

Iterate through all journals in given folder.

Warning

This function is from ancient times and needs to be updated. It might have grown old and grumpy. Expect it to change in the near future.

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.

load(name, project, batch_col=None, allow_from_journal=True, allow_using_backup_journal=False, drop_bad_cells=True, force_reload=False, reader='default', reader_path=None, journal_file=None, **kwargs)[source]#

Load a batch from a journal file or create a new batch and load it if the journal file does not exist.

Parameters:

name (str) – name of batch
project (str) – name of project
batch_col (str) – batch column identifier (only used for loading from db with simple_db_reader)
allow_from_journal (bool) – if True, the journal file will be loaded if it exists
autoload_batch_journal) ((should be renamed to)
allow_using_backup_journal (bool) – if True, the backup journal file will be used if the journal file does not exist
force_reload (bool) – if True, the batch will be reloaded even if the journal file exists
drop_bad_cells (bool) – if True, bad cells will be dropped (only apply if journal file is loaded)
auto_use_file_list (bool) – Experimental feature. If True, a file list will be generated and used instead of searching for files in the folders.
reader (str) – reader to use (defaults to “default” as given in the config-file or prm-class).
reader_path (str) – path to the reader file (if not using “simple_excel_reader”). When journal_file is provided with a JSON reader, journal_file is used as the DB source and overrides reader_path.
journal_file (str or pathlib.Path, optional) – explicit path to a journal/JSON file. When provided, load from this file instead of the derived path or DB-only path. If reader is "batbase_json_reader" or "custom_json_reader", this file is used as the DB source (no need to set reader_path).
**kwargs – sent to Batch during initialization

Keyword Arguments:

db_reader (str) – data-base reader to use (defaults to “default” as given in the config-file or prm-class).
frame (pandas.DataFrame) – load from given dataframe.
default_log_level (str) – custom log-level (defaults to None (i.e. default log-level in cellpy)).
custom_log_dir (str or pathlib.Path) – custom folder for putting the log-files.
force_raw_file (bool) – load from raw regardless (defaults to False).
force_cellpy (bool) – load cellpy-files regardless (defaults to False).
force_recalc (bool) – Always recalculate (defaults to False).
export_cycles (bool) – Extract and export individual cycles to csv (defaults to True).
export_raw (bool) – Extract and export raw-data to csv (defaults to True).
export_ica (bool) – Extract and export individual dQ/dV data to csv (defaults to True).
accept_errors (bool) – Continue automatically to next file if error is raised (defaults to False).
nom_cap (float) – give a nominal capacity if you want to use another value than the one given in the config-file or prm-class.
max_cycle (int or None) – maximum number of cycles to link up to (defaults to None).
force_combine_summaries (bool) – automatically run combine_summaries when linking.
column_map (dict) – for reader="custom_json_reader", map from JSON column names to cellpy journal keys (e.g. {"cell_id": "filename", "mass_mg": "mass"}).

Returns:

populated Batch object (cellpy.utils.batch.Batch)

Examples

Load from derived journal (default): look for cellpy_batch_{name}.json in cwd or project:

b = load("my_batch", "my_project")

Load from an explicit cellpy journal file:

b = load("my_batch", "my_project", journal_file="path/to/cellpy_batch_my_batch.json")

Load from a custom JSON file using a column map:

b = load(
    "my_batch", "my_project",
    journal_file="path/to/cells.json",
    reader="custom_json_reader",
    column_map={"cell_id": "filename", "mass_mg": "mass"},
)

Load from a BatBase-format JSON file:

b = load("my_batch", "my_project", journal_file="path/to/batbase.json", reader="batbase_json_reader")

load_journal(journal_file, **kwargs)[source]#

Load a journal file.

Parameters:

journal_file (str) – path to journal file.
**kwargs – sent to Journal.from_file

Returns:

journal

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

naked(name=None, project=None) → Batch[source]#

Returns an empty instance of the Batch class.

Examples

>>> empty_batch = naked()

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.

Warning

This function is from ancient times and needs to be updated. It might have grown old and grumpy. Expect it to change in the near future.

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.collectors module#

cellpy.utils.diagnostics module#

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

first_cycle_irreversible_capacity()[source]#

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

get_effective_C_rates(steptable)[source]#

get_effective_C_rates_and_caps(steptable)[source]#

help()[source]#: Method of the EasyPlot class which prints some helptext in addition to all supported params.

main()[source]#

cellpy.utils.example_data module#

Tools for getting some data to play with

class ExampleData(*values)[source]#

Bases: Enum

Enum for example data files

ARBIN = '20160805_test001_45_cc_01.res'#

AUX_MULTI_X = 'aux_multi_x.res'#

CELLPY = '20180418_sf033_4_cc.h5'#

CUSTOM = 'custom_data.csv'#

CUSTOM_EXCEL = 'custom_data.xlsx'#

CUSTOM_INSTRUMENT = 'custom_instrument.yml'#

LOCAL_INSTRUMENT = 'local_instrument.yml'#

MACCOR_TXT_TYPE_ONE = 'maccor_one.txt'#

MACCOR_TXT_TYPE_THREE = 'maccor_three.txt'#

MACCOR_TXT_TYPE_TWO = 'maccor_two.txt'#

NEWARE_CSV = 'neware_uio.csv'#

OLD_CELLPY = '20160805_test001_45_cc.h5'#

PEC_CSV = 'pec.csv'#

RATE = '20231115_rate_cc.h5'#

arbin_file_path() → Path[source]#: Get the path to an example arbin res file

arbin_multi_file_path() → Path[source]#: Get the path to an example arbin res file

biologics_file_path() → Path[source]#: Get the path to an example biologics mpr file

cellpy_file(testing: bool = False) → CellpyCell[source]#

load an example cellpy file.

Parameters:: testing (bool) – run in test mode
Returns:: cellpy.CellpyCell object with the data loaded

cellpy_file_path() → Path[source]#: Get the path to an example cellpy file

custom_file_path() → Path[source]#: Get the path to an example custom data csv file

custom_instrument_path() → Path[source]#: Get the path to an example custom instrument definition yaml file

custom_xlsx_file_path() → Path[source]#: Get the path to an example custom data Excel file

download_all_files()[source]#: Download all example data files from the cellpy-data repository.

download_file(url, local_filename)[source]#

Download a file from the web.

Parameters:

url (str) – URL of the file to download
local_filename (str) – Local filename to save the file to

local_instrument_path() → Path[source]#: Get the path to an example local-instrument definition yaml file for loading csv-type files

maccor_file_path() → Path[source]#: Get the path to an example maccor txt file

maccor_file_path_type_one() → Path[source]#: Get the path to an example maccor txt file

maccor_file_path_type_three() → Path[source]#: Get the path to an example maccor txt file

maccor_file_path_type_two() → Path[source]#: Get the path to an example maccor txt file

neware_file_path() → Path[source]#: Get the path to an example neware csv file

old_cellpy_file_path() → Path[source]#: Get the path to an example cellpy file

pec_file_path() → Path[source]#: Get the path to an example pec csv file

rate_file()[source]#: Get the path to an example cellpy file with rate data

raw_file(auto_summary: bool = True, testing: bool = False) → CellpyCell[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.CellpyCell object with the data loaded

cellpy.utils.helpers module#

add_areal_capacity(cell, cell_id, journal)[source]#: Adds areal capacity to the summary.

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 (CellpyCell) – 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:

data object.

add_cv_step_columns(columns: list) → list[source]#: Add columns for CV steps.

add_normalized_capacity(cell, norm_cycles=None, individual_normalization=False, scale=1.0)[source]#

Add normalized capacity to the summary.

Parameters:

cell (CellpyCell) – 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.

add_normalized_cycle_index(summary, nom_cap, 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) – data summary
nom_cap (float) – nominal capacity to use when normalizing.
column_name (str) – name of the new column. Uses the name defined in cellpy.parameters.internal_settings as default.

Returns:

data object now with normalized cycle index in its summary.

check_connection(path=None)[source]#

collect_frames(frames, group_it: bool, hdr_norm_cycle: str, keys: list, normalize_cycles: bool, hooks: list = None)[source]#: Helper function for concat_summaries.

concat_summaries(b: Batch, 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, group_it=False, custom_group_labels=None, rate_std=None, rate_column=None, inverse=False, inverted=False, key_index_bounds=None, pages=None, recalc_summary_kwargs=None, recalc_step_table_kwargs=None, only_selected=False, experimental_feature_cell_selector=None, partition_by_cv=False, replace_inf_with_nan=True, individual_summary_hooks=None, concatenated_summary_hooks=None, drop_columns=None, average_method='mean', replace_extremes_with_nan=True, low_limit=-1000000.0, high_limit=1000000.0, *args, **kwargs) → DataFrame[source]#

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

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 attribute name) [defaults to “charge_capacity_gravimetric”]
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 normalization of the cycle numbers (also called equivalent cycle index)
group_it (bool) – if True, average pr group.
partition_by_cv (bool) – if True, partition the data by cv_step.
custom_group_labels (dict) – dictionary of custom labels (key must be the group number/name).
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.
key_index_bounds (list) – used when creating a common label for the cells by splitting the label on ‘_’ and combining again using the key_index_bounds as start and end index.
pages (pandas.DataFrame) – alternative pages (journal) of the batch object (if not given, it will use the pages from the batch object).
recalc_summary_kwargs (dict) – keyword arguments to be used when recalculating the summary. If not given, it will not recalculate the summary.
recalc_step_table_kwargs (dict) – keyword arguments to be used when recalculating the step table. If not given, it will not recalculate the step table.
only_selected (bool) – only use the selected cells.
experimental_feature_cell_selector (list) – list of cell names to select.
partition_by_cv – if True, partition the data by cv_step.
replace_inf_with_nan (bool) – if True, replace inf with nan in the summary data.
individual_summary_hooks (list) – list of functions to be applied to the individual summary data.
concatenated_summary_hooks (list) – list of functions to be applied to the concatenated summary data (passed to the collect_frames function).
drop_columns (list) – list of columns to drop before concatenation.
average_method (str) – method to be used when averaging the summary data. Remark that for backward compatibility, the column name will be “mean” regardless of the actual method used.
replace_extremes_with_nan (bool) – if True, replace values outside the range [low_limit, high_limit] with nan in the summary data.
low_limit (float) – lower limit for replacing extremes with nan if replace_extremes_with_nan is True.
high_limit (float) – upper limit for replacing extremes with nan if replace_extremes_with_nan is True.
remove_last (bool) – if True, remove the last cycle from the summary data.
*args – additional arguments to be passed to the hooks.
**kwargs –
additional arguments to be passed to the hooks.

Returns:

pandas.DataFrame

concatenate_summaries(b: Batch, 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, group_it=False, custom_group_labels=None, rate_std=None, rate_column=None, inverse=False, inverted=False, key_index_bounds=None) → DataFrame[source]#

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

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 attribute name) [defaults to “charge_capacity_gravimetric”]
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 normalization of the cycle numbers (also called equivalent cycle index)
group_it (bool) – if True, average pr group.
custom_group_labels (dict) – dictionary of custom labels (key must be the group number/name).
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.
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].

Returns:

pandas.DataFrame

create_group_names(custom_group_labels, gno, key_index_bounds, keys_sub, pages)[source]#

Helper function for concat_summaries.

The prioritisation of methods for creating the group name is as follows: 1. custom_group_labels (if given) 2. group_label in pages (if given) 3. key_index_bounds and keys_sub (if no other option is available)

Parameters:

custom_group_labels (dict) – dictionary of custom labels (key must be the group number).
gno (int) – group number.
key_index_bounds (list) – used when creating a common label for the cells by splitting the label on ‘_’ and combining again using the key_index_bounds as start and end index.
keys_sub (list) – list of keys.
pages (pandas.DataFrame) – pages (journal) of the batch object. If the column “group_label” is present, it will be used to create the group name.

create_rate_column(df, nom_cap, spec_conv_factor, column='current_avr')[source]#: Adds a rate column to the dataframe (steps).

filter_cells()[source]#

Filter cells based on some criteria.

This is a helper function that can be used to filter cells based on some criteria. It is not very flexible, but it is easy to use.

Returns:: a list of cell names that passed the criteria.

fix_group_names(keys)[source]#: Helper function for concat_summaries.

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)

make_new_cell()[source]#: create an empty CellpyCell object.

remove_first_cycles_from_summary(s, first=None)[source]#: Remove last rows after given cycle number

remove_last_cycles_from_summary(s, last=None)[source]#: Remove last rows after given cycle number

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

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:

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:

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 on neighbours

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)

select_summary_based_on_rate(cell, rate=None, on=None, rate_std=None, rate_column=None, inverse=False, inverted=False, fix_index=True, partition_by_cv=False)[source]#

Select only cycles charged or discharged with a given rate.

Parameters:

cell (cellpy.CellpyCell)
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).

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

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

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

yank_outliers(b: Batch, 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.ica module#

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

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

dqdv(cell, split=False, tidy=True, label_direction=False, **kwargs)[source]#

Calculates dq-dv data for all cycles contained in the given CellpyCell object, returns data as pandas.DataFrame(s)

Parameters:

cell (CellpyCell-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.dqdv(my_cell, split=True)
>>> charge_df.plot(x="voltage",y="dq")

dqdv_cycle(cycle_df, splitter=True, label_direction=False, **kwargs)[source]#

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

Returns a tuple of numpy arrays with ‘voltage’ and ‘incremental_capacity’.

Parameters:

cycle_df (pandas.DataFrame) – the cycle data (‘voltage’, ‘capacity’, ‘direction’ (1 or -1)).
splitter (bool) – insert a np.nan row between charge and discharge.
label_direction (bool) – include ‘direction’ (1 or -1).

Returns:

Returns a tuple of numpy arrays with ‘voltage’ and ‘incremental_capacity’.

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)

dqdv_cycles(cycles_df, not_merged=False, label_direction=False, **kwargs)[source]#

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

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

Parameters:

cycles_df (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).
label_direction (bool) – include ‘direction’ (1 or -1).

Returns:

pandas.DataFrame with columns ‘cycle’, ‘voltage’, ‘dq’ (and ‘direction’ if label_direction is 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

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

dqdv_np(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 arrays of 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)

index_bounds(x)[source]#: Returns tuple with first and last item.

value_bounds(x)[source]#: Returns tuple with min and max in x.

cellpy.utils.live module#

Routines for streaming cell data

cellpy.utils.ocv_rlx module#

class MultiCycleOcvFit(cellpydata, cycles, circuits=3)[source]#

Bases: object

Object for performing fitting of multiple cycles.

Remarks:

This is only tested for OCV relaxation data for half-cells in anode mode where the OCV relaxation is performed according to the standard protocol implemented at IFE in the battery development group.

If you want to use this for other data or protocols, please report an issue on the GitHub page.

static create_colormap(name='plasma', cycles=None)[source]#

property cycles#

find_zero(cycle, direction)[source]#

get_best_fit_data()[source]#: Returns the best fit data.

get_best_fit_parameters() → list[source]#: Returns parameters for the best fit.

get_best_fit_parameters_grouped() → dict[source]#: Returns a dictionary of the best fit.

get_best_fit_parameters_translated() → list[source]#: Returns the parameters in ‘real units’ for the best fit.

get_best_fit_parameters_translated_grouped() → dict[source]#: Returns the parameters as a dictionary of the ‘real units’ for the best fit.

get_fit_cycles()[source]#: Returns a list of 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 CellpyCell.

summary_translated() → DataFrame[source]#: Convenience function for creating a dataframe of the summary of the fit (translated)

class OcvFit(circuits=None, direction=None, zero_current=0.1, zero_voltage=0.05)[source]#

Bases: object

Class for fitting open circuit relaxation data.

The model is a sum of exponentials and a constant offset (Ohmic resistance). The number of exponentials is set by the number of circuits. The model is:

v(t) = v0 + R0 + sum(wi * exp(-t/tau_i)) where v0 is the OCV, wi is the weight of the exponential tau_i is the time constant of the exponential and R0 is the Ohmic resistance.

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 fit is performed by using lmfit.

data#

The data to be fitted.

Type:: cellpydata-object

time#

Time measured during relaxation (extracted from data if provided).

Type:: list

voltage#

Time measured during relaxation (extracted from data if provided).

Type:: list

steps#

Step information (if data is provided).

Type:: str

circuits#

The number of circuits to be fitted.

Type:: int

weights#

The weights of the different circuits.

Type:: list

zero_current#

Last current observed before turning the current off.

Type:: float

zero_voltage#

Last voltage observed before turning the current off.

Type:: float

model#

The model used for fitting.

Type:: lmfit-object

params#

The parameters used for fitting.

Type:: lmfit-object

result#

The result of the fitting.

Type:: lmfit-object

best_fit_data#

The best fit data [x, y_measured, y_fitted].

Type:: list

best_fit_parameters#

The best fit parameters.

Type:: dict

Remarks:

This class does not take advantage of the cellpydata-object. It is primarily used for fitting data that does not originate from cellpy, but it can also be used for fitting cellpy-data.

If you have cellpy-data, you should use the MultiCycleOcvFit class instead.

create_model()[source]#: Create the model to be used in the fit.

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]#

Convenience method for setting the data from a cellpydata-object. :param cellpydata: data object from cellreader :type cellpydata: CellpyCell :param cycle: cycle number to get from CellpyCell object :type cycle: int

Remarks:: You need to set the direction before calling this method if you don’t want to use the default direction (up).

Returns:: None

set_circuits(circuits)[source]#

Set the number of circuits to be used in the fit.

Parameters:: circuits (int) – number of circuits to be used in the fit. Can be 1 to 4.

set_data(t, v)[source]#: Set the data to be fitted.

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]#

fit(c, direction='up', circuits=3, cycles=None, return_fit_object=False)[source]#

Fits the OCV steps in CellpyCell object c.

Parameters:

c – CellpyCell object
direction – direction of the OCV steps (‘up’ or ‘down’)
circuits – number of circuits to use (first is IR, rest is RC) in the fitting (min=1, max=4)
cycles – list of cycles to fit (if None, all cycles will be used)
return_fit_object – if True, returns the MultiCycleOcvFit instance.

Returns:

pd.DataFrame with the fitted parameters for each cycle if return_fit_object=False, else MultiCycleOcvFit instance

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.

class CyclesPlotterConfig(form_cycles: DataFrame | None = None, rest_cycles: DataFrame | None = None, fig_title: str | None = None, capacity_unit: str | None = None, plotly_template: str | None = None, force_colorbar: bool = False, force_nonbar: bool = False, figsize: tuple = (6, 4), cbar_aspect: int = 30, colormap: str = 'Blues_r', formation_colormap: str = 'autumn', cut_colorbar: bool = True, width: int = 600, height: int = 400, marker_size: int = 5, formation_line_color: str = 'rgba(152, 0, 0, .8)', xlim: list[float] | None = None, ylim: list[float] | None = None, n_rest_cycles: int | None = None, n_form_cycles: int | None = None, show_formation: bool = True, seaborn_style_dict: dict | None = None, seaborn_context: str = 'notebook', seaborn_facecolor: str = '#EAEAF2', seaborn_edgecolor: str = 'black', seaborn_style: str = 'dark', seaborn_palette: str = 'deep')[source]#

Bases: object

Configuration dataclass for cycles_plot parameters.

Encapsulates all parameters for cycles_plot to improve maintainability and enable easier refactoring. Note that ‘c’ (cellpy object) and ‘df’ (dataframe) are passed separately as they are data objects, not configuration.

capacity_unit: str | None = None#

cbar_aspect: int = 30#

colormap: str = 'Blues_r'#

cut_colorbar: bool = True#

fig_title: str | None = None#

figsize: tuple = (6, 4)#

force_colorbar: bool = False#

force_nonbar: bool = False#

form_cycles: DataFrame | None = None#

formation_colormap: str = 'autumn'#

formation_line_color: str = 'rgba(152, 0, 0, .8)'#

height: int = 400#

marker_size: int = 5#

n_form_cycles: int | None = None#

n_rest_cycles: int | None = None#

plotly_template: str | None = None#

rest_cycles: DataFrame | None = None#

seaborn_context: str = 'notebook'#

seaborn_edgecolor: str = 'black'#

seaborn_facecolor: str = '#EAEAF2'#

seaborn_palette: str = 'deep'#

seaborn_style: str = 'dark'#

seaborn_style_dict: dict | None = None#

show_formation: bool = True#

width: int = 600#

xlim: list[float] | None = None#

ylim: list[float] | None = None#

class PlotlyPlotBuilder[source]#

Bases: object

Handles Plotly-specific plotting logic for summary plots.

This class extracts the Plotly plotting logic from summary_plot_legacy to improve maintainability and testability.

build_plot(data: DataFrame, prepared_data_info: dict, config: SummaryPlotConfig, additional_kwargs: dict, c: Any) → Any[source]#

Build Plotly figure from prepared data.

Parameters:

data – Prepared DataFrame from SummaryPlotDataPreparer
prepared_data_info – Dictionary with metadata from data preparer
config – SummaryPlotConfig with all parameters
additional_kwargs – Additional kwargs for plotly (from legacy function)
c – cellpy object (needed for some label generation)

Returns:

Plotly figure object

class SeabornPlotBuilder[source]#

Bases: object

Handles Seaborn-specific plotting logic for summary plots.

This class extracts the Seaborn plotting logic from summary_plot_legacy to improve maintainability and testability.

build_plot(data: DataFrame, prepared_data_info: dict, config: SummaryPlotConfig, additional_kwargs: dict, c: Any) → Any[source]#

Build Seaborn/Matplotlib figure from prepared data.

Parameters:

data – Prepared DataFrame from SummaryPlotDataPreparer
prepared_data_info – Dictionary with metadata from data preparer
config – SummaryPlotConfig with all parameters
additional_kwargs – Additional kwargs for seaborn (from legacy function)
c – cellpy object (needed for some label generation)

Returns:

Matplotlib figure object

class SummaryPlotConfig(x: str | None = None, y: str = 'capacities_gravimetric_coulombic_efficiency', height: int | None = None, width: int = 900, markers: bool = True, title: str | None = None, x_range: list | None = None, y_range: list | None = None, ce_range: list | None = None, norm_range: list | None = None, cv_share_range: list | None = None, split: bool = True, hover_columns: list | None = None, auto_convert_legend_labels: bool = True, interactive: bool = True, share_y: bool = False, rangeslider: bool = False, return_data: bool = False, verbose: bool = False, plotly_template: str | None = None, seaborn_palette: str = 'deep', seaborn_style: str = 'dark', formation_cycles: int = 3, show_formation: bool = True, show_legend: bool = True, x_axis_domain_formation_fraction: float = 0.2, column_separator: float = 0.01, reset_losses: bool = True, link_capacity_scales: bool = False, fullcell_standard_normalization_type: str = 'max', fullcell_standard_normalization_factor: float | None = None, fullcell_standard_normalization_scaler: float = 1.0, fullcell_standard_normalization_cycle_numbers: list[int] | None = None, seaborn_line_hooks: list[tuple[str, list, dict]] | None=None, filters: dict | None = None, nominal_capacity: float | None = None, rate_filter_columns: str | tuple | list | None = None, additional_kwargs: dict = <factory>)[source]#

Bases: object

Configuration dataclass for summary_plot parameters.

Encapsulates all parameters for summary_plot to improve maintainability and enable easier refactoring.

additional_kwargs: dict#

auto_convert_legend_labels: bool = True#

ce_range: list | None = None#

column_separator: float = 0.01#

cv_share_range: list | None = None#

filters: dict | None = None#

formation_cycles: int = 3#

classmethod from_kwargs(**kwargs) → SummaryPlotConfig[source]#

Create SummaryPlotConfig from keyword arguments.

Extracts known parameters and stores remaining kwargs in additional_kwargs.

fullcell_standard_normalization_cycle_numbers: list[int] | None = None#

fullcell_standard_normalization_factor: float | None = None#

fullcell_standard_normalization_scaler: float = 1.0#

fullcell_standard_normalization_type: str = 'max'#

height: int | None = None#

hover_columns: list | None = None#

interactive: bool = True#

link_capacity_scales: bool = False#

markers: bool = True#

nominal_capacity: float | None = None#

norm_range: list | None = None#

plotly_template: str | None = None#

rangeslider: bool = False#

rate_filter_columns: str | tuple | list | None = None#

reset_losses: bool = True#

return_data: bool = False#

seaborn_line_hooks: list[tuple[str, list, dict]] | None = None#

seaborn_palette: str = 'deep'#

seaborn_style: str = 'dark'#

share_y: bool = False#

show_formation: bool = True#

show_legend: bool = True#

split: bool = True#

title: str | None = None#

to_kwargs() → dict[source]#: Convert config back to kwargs dict for passing to legacy function.

verbose: bool = False#

width: int = 900#

x: str | None = None#

x_axis_domain_formation_fraction: float = 0.2#

x_range: list | None = None#

y: str = 'capacities_gravimetric_coulombic_efficiency'#

y_range: list | None = None#

class SummaryPlotDataPreparer[source]#

Bases: object

Handles data collection and transformation for summary plots.

This class extracts the data preparation logic from summary_plot_legacy to improve maintainability and testability.

prepare_data(c: Any, config: SummaryPlotConfig, plot_info: SummaryPlotInfo) → dict[source]#

Prepare data for plotting.

Parameters:

c – cellpy object
config – SummaryPlotConfig with all parameters
summary_plot_info – SummaryPlotInfo containing information about pre-defined columns and labels

Returns:

data: prepared DataFrame
number_of_rows: number of rows for subplot layout
x_label: x-axis label
y_label: y-axis label
max_cycle: maximum cycle number
min_cycle: minimum cycle number
max_val_normalized_col: max value for normalized columns
formation_cycle_selector: boolean selector for formation cycles

Return type:

Dictionary with keys

class SummaryPlotInfo(c: Any)[source]#

Bases: object

static normalize_col(x: ndarray, normalization_factor: float | None = None, normalization_type: str = 'max', normalization_scaler: float = 1.0, normalization_indexes: list[int] = [1]) → ndarray[source]#

Normalize a column.

Parameters:

x – column to normalize
normalization_factor – normalization factor
normalization_type – normalization type
normalization_scaler – normalization scaler
normalization_indexes – indexes to use for normalization

Normalization types:

divide: divide by normalization factor and then multiply by normalization scaler
shift-divide: shift by normalization factor and then
divide by normalization factor and then multiply by normalization scaler
multiply: multiply by normalization factor and normalization scaler
area: divide by area (integrated using trapezoid rule) and then multiply by normalization scaler
max: divide by maximum value and then multiply by normalization scaler
on-max: divide by maximum value over normalization factor and then multiply by normalization scaler
on-cycles: divide by mean value of the cycles in normalization_indexes and then multiply by normalization scaler
false: no normalization is done

Returns:: normalized column

x_axis_labels: dict | None = None#

x_cols: tuple | None = None#

x_trans: dict | None = None#

y_axis_label: dict | None = None#

y_cols: dict | None = None#

y_trans: dict | None = None#

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)

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)

create_plotly_default_template(name='all_axis', font_color='#455A64', marker_edge_on=False, marker_size=12, marker_edge_color='white', marker_width=None, opacity=0.8)[source]#

cycle_info_plot(cell, cycle=None, get_axes=False, interactive=True, t_unit='hours', v_unit='V', i_unit='mA', **kwargs)[source]#

Show raw data together with step and cycle information.

Parameters:

cell – cellpy object
cycle (int or list or tuple) – cycle(s) to select (must be int for matplotlib)
get_axes (bool) – return axes (for matplotlib) or figure (for plotly)
interactive (bool) – use interactive plotting (if available)
t_unit (str) – unit for x-axis (default: “hours”)
v_unit (str) – unit for y-axis (default: “V”)
i_unit (str) – unit for current (default: “mA”)
**kwargs – parameters specific to plotting backend.

Returns:

matplotlib.axes or None

cycles_plot(*args, **kwargs)[source]#

Plot the voltage vs. capacity for different cycles of a cell.

This function is meant as an easy way of visualizing the voltage vs. capacity for different cycles of a cell. The cycles are plotted with different colors, and the formation cycles are highlighted with a different colormap. It is not intended to provide you with high quality plots, but rather to give you a quick overview of the data.

Parameters:

c – cellpy object containing the data to plot.
cycles (list, optional) – List of cycle numbers to plot. If None, all cycles are plotted.
inter_cycle_shift (bool, optional) – Whether to shift the cycles by one. Default is True.
cycle_mode (str, optional) – Mode for the test (anode or other). Default is None (i.e. use the cellpy cell object’s cycle_mode).
formation_cycles (int, optional) – Number of formation cycles to highlight. Default is 3.
show_formation (bool, optional) – Whether to show formation cycles. Default is True.
mode (str, optional) – Mode for capacity (‘gravimetric’, ‘areal’, etc.). Default is ‘gravimetric’.
method (str, optional) – Method for interpolation. Default is ‘forth-and-forth’.
interpolated (bool, optional) – Whether to interpolate the data. Default is True.
number_of_points (int, optional) – Number of points for interpolation. Default is 200.
colormap (str, optional) – Colormap for the cycles. Default is ‘Blues_r’.
formation_colormap (str, optional) – Colormap for the formation cycles. Default is ‘autumn’.
cut_colorbar (bool, optional) – Whether to cut the colorbar. Default is True.
title (str, optional) – Title of the plot. If None, the cell name is used.
figsize (tuple, optional) – Size of the figure for matplotlib. Default is (6, 4).
xlim (list, optional) – Limits for the x-axis.
ylim (list, optional) – Limits for the y-axis.
interactive (bool, optional) – Whether to use interactive plotting (Plotly). Default is True.
return_figure (bool, optional) – Whether to return the figure object. Default is opposite of interactive.
width (int, optional) – Width of the figure for Plotly. Default is 600.
height (int, optional) – Height of the figure for Plotly. Default is 400.
marker_size (int, optional) – Size of the markers for Plotly. Default is 5.
formation_line_color (str, optional) – Color for the formation cycle lines in Plotly. Default is ‘rgba(152, 0, 0, .8)’.
force_colorbar (bool, optional) – Whether to force the colorbar to be shown. Default is False.
force_nonbar (bool, optional) – Whether to force the colorbar to be hidden. Default is False.
plotly_template (str, optional) – Plotly template to use (uses default template if None).
seaborn_palette – name of the seaborn palette to use (only if seaborn is available).
seaborn_style – name of the seaborn style to use (only if seaborn is available).
return_data (bool, optional) – Whether to return the data used for the plot. Default is False.
**kwargs – Additional keyword arguments for the plotting backend.

Additional keyword arguments for Plotly:: plotly_max_individual_traces_for_lines (int, optional): Maximum number of individual traces (not including formation cycles) for lines in Plotly. Default is 8. plotly_xaxes_kwargs (dict, optional): propagated to plotly.update_xaxes. plotly_yaxes_kwargs (dict, optional): propagated to plotly.update_yaxes. plotly_layout_kwargs (dict, optional): propagated to plotly.update_layout.

Returns:

The figure is a matplotlib.figure.Figure or a plotly.graph_objects.Figure, depending on the backend used. If return_data is True:

tuple: (figure, data)

If return_figure is True:: figure: The generated plot figure (same as the return value).
Else:: None: The plot is shown in the default browser.

load_figure(filename, backend=None)[source]#: Load figure from file.

load_matplotlib_figure(filename, create_new_manager=False)[source]#

load_plotly_figure(filename)[source]#: Load plotly figure from file.

make_matplotlib_manager(fig)[source]#: Create a new manager for a matplotlib figure.

notebook_docstring_printer(func, default_show_docstring=False)[source]#

Decorator that prints the function’s docstring when called from a notebook environment.

This decorator checks if the function is being called from a Jupyter notebook or IPython environment and prints the function’s docstring if it is.

Parameters:: func – The function to decorate
Returns:: The decorated function

partition_summary_cv_steps(c, x: str, column_set: list, split: bool = False, var_name: str = 'variable', value_name: str = 'value')[source]#

Partition the summary data into CV and non-CV steps.

Parameters:

c – cellpy object
x – x-axis column name
column_set – names of columns to include
split – add additional column that can be used to split the data when plotting.
var_name – name of the variable column after melting
value_name – name of the value column after melting

Returns:

pandas.DataFrame (melted with columns x, var_name, value_name, and optionally “row” if split is True)

raw_plot(cell, y=None, y_label=None, x=None, x_label=None, title=None, interactive=True, plot_type='voltage-current', double_y=True, **kwargs)[source]#

Plot raw data.

Parameters:

cell – cellpy object
y (str or list) – y-axis column
y_label (str or list) – label for y-axis
x (str) – x-axis column
x_label (str) – label for x-axis
title (str) – title of the plot
interactive (bool) – use interactive plotting
plot_type (str) – type of plot (defaults to “voltage-current”) (overrides given y if y is not None), currently only “voltage-current”, “raw”, “capacity”, “capacity-current”, and “full” is supported.
double_y (bool) – use double y-axis (only for matplotlib and when plot_type with 2 rows is used)
**kwargs – additional parameters for the plotting backend

Returns:

matplotlib figure or plotly figure

save_image_files(*args, **kwargs)[source]#

Save to image files (png, svg, json/pickle).

Notes

This method requires kaleido for the plotly backend.

Notes

Exporting to json is only applicable for the plotly backend.

Parameters:

figure (fig-object) – The figure to save.
name (pathlib.Path or str) – The path of the file (without extension).
scale (float) – The scale of the image.
dpi (int) – The dpi of the image.
backend (str) – The backend to use (plotly or seaborn/matplotlib).
formats (list) – The formats to save (default: [“png”, “svg”, “json”, “pickle”]).

save_matplotlib_figure(fig, filename)[source]#

set_plotly_template(template_name=None, **kwargs)[source]#: Set the default plotly template.

summary_plot(*args, **kwargs)[source]#

Create a summary plot.

This is a wrapper around summary_plot_legacy for backwards compatibility. During refactoring, this will be gradually replaced with a new implementation.

Parameters:

c – cellpy object
x – x-axis column (default: ‘cycle_index’)
y – y-axis column or column set. Currently, the following predefined sets exists: “voltages”, “capacities_gravimetric”, “capacities_areal”, “capacities_absolute”, “capacities_gravimetric_split_constant_voltage”, “capacities_areal_split_constant_voltage”, “capacities_gravimetric_coulombic_efficiency”, “capacities_areal_coulombic_efficiency”, “capacities_absolute_coulombic_efficiency”, “capacities_gravimetric_with_rate”, “capacities_areal_with_rate”, “capacities_absolute_with_rate”, “fullcell_standard_gravimetric”, “fullcell_standard_areal”, “fullcell_standard_absolute”,
height – height of the plot (for plotly)
width – width of the plot (for plotly)
markers – use markers
title – title of the plot
x_range – limits for x-axis
y_range – limits for y-axis
ce_range – limits for coulombic efficiency (if present)
norm_range – limits for normalized capacity (if present)
cv_share_range – limits for cv share (if present)
split – split the plot
hover_columns – columns to show in the hover tooltip (only for plotly)
auto_convert_legend_labels – convert the legend labels to a nicer format.
interactive – use interactive plotting (plotly)
rangeslider – add a range slider to the x-axis (only for plotly)
share_y – share y-axis (only for plotly)
return_data – return the data used for plotting
verbose – print out some extra information to make it easier to find out what to plot next time
plotly_template – name of the plotly template to use
seaborn_palette – name of the seaborn palette to use
seaborn_style – name of the seaborn style to use
formation_cycles – number of formation cycles to show
show_formation – show formation cycles
show_legend – show the legend
x_axis_domain_formation_fraction – fraction of the x-axis domain for the formation cycles (default: 0.2)
column_separator – separation between columns when splitting the plot (only for plotly)
reset_losses – reset the losses to the first cycle (only for fullcell_standard plots)
link_capacity_scales – link the capacity scales (only for fullcell_standard plots)
fullcell_standard_normalization_type – normalization type for the fullcell standard plots (capacity retention) (divide, multiply, area, max, on-max, False)
fullcell_standard_normalization_factor – normalization factor for the fullcell standard plots
fullcell_standard_normalization_scaler – scaler for the fullcell standard plots
fullcell_standard_normalization_cycle_numbers – cycle numbers to use for normalization (only for fullcell_standard plots)
seaborn_line_hooks – list of functions to hook into the seaborn lines (e.g. to update the marker_size)
filters – optional dict forwarded to cellpy.filters.filter_summary() to drop rows from the summary before plotting (e.g. filters={"rate": (0, 0.5)} drops slow-rate characterisation cycles). See cellpy.filters.filter_summary() for range semantics.
nominal_capacity – optional plain float in c.cellpy_units.nominal_capacity units. When given, the charge_c_rate / discharge_c_rate columns are rescaled to use this nominal capacity instead of c.data.nom_cap (multiplies rates by c.data.nom_cap / nominal_capacity).
rate_filter_columns – optional override for which rate column(s) the rate filter targets. Defaults to both (charge_c_rate, discharge_c_rate); pass a single string (e.g. "discharge_c_rate") to filter only one side.
**kwargs – includes additional parameters for the plotting backend (not properly documented yet).

Returns:

if return_data is True, returns a tuple with the figure and the data used for plotting. Otherwise, it returns only the figure. If interactive is True, the figure is a plotly figure, else it is a matplotlib figure.

Examples

Default plot (capacity and Coulombic efficiency vs cycle number):

>>> from cellpy.utils.plotutils import summary_plot
>>> fig = summary_plot(c)
>>> fig.show()

Plot gravimetric capacity alone, with formation cycles disabled:

>>> fig = summary_plot(c, y="capacities_gravimetric", show_formation=False)

Use the non-interactive (matplotlib/seaborn) backend, e.g. for an SVG export from a script:

>>> fig = summary_plot(c, y="capacities_gravimetric", interactive=False)
>>> fig.savefig("summary.svg")

Get the prepared DataFrame back together with the figure (useful for custom annotations or follow-up analysis):

>>> fig, data = summary_plot(c, y="capacities_gravimetric", return_data=True)
>>> data.head()

New *_with_rate y-set adds a C-rate subplot on row 0:

>>> fig = summary_plot(c, y="capacities_gravimetric_with_rate")

Drop slow-rate characterisation cycles (e.g. keep only rows where both charge_c_rate and discharge_c_rate are above 0.1):

>>> fig = summary_plot(
...     c,
...     y="capacities_gravimetric",
...     filters={"rate": (0.1, 10.0)},
... )

Same idea using the symmetric {value, delta} form to keep rows close to a target C/2 rate:

>>> fig = summary_plot(
...     c,
...     y="capacities_gravimetric_with_rate",
...     filters={"rate": {"value": 0.5, "delta": 0.05}},
... )

Filter on the discharge rate only (charge rate is ignored):

>>> fig = summary_plot(
...     c,
...     y="capacities_gravimetric",
...     filters={"rate": (0.1, 1.0)},
...     rate_filter_columns="discharge_c_rate",
... )

Override the nominal capacity used for the C-rate axis without re-running make_summary. The rate columns are rescaled by c.data.nom_cap / nominal_capacity; here we both rescale and filter in the new units:

>>> fig = summary_plot(
...     c,
...     y="capacities_gravimetric_with_rate",
...     nominal_capacity=200.0,
...     filters={"rate": (0.1, 5.0)},
... )

The same filter is available without plotting via CellpyCell.filtered_summary() (returns a DataFrame copy):

>>> trimmed = c.filtered_summary(rate=(0.1, 10.0))

Or as a free function on any summary-shaped DataFrame:

>>> from cellpy.filters import filter_summary
>>> trimmed = filter_summary(c.data.summary.reset_index(),
...                          rate=(0.1, 10.0))

summary_plot_legacy(*args, **kwargs)[source]#

Create a summary plot.

Parameters:

c – cellpy object
x – x-axis column (default: ‘cycle_index’)
y – y-axis column or column set. Currently, the following predefined sets exists: “voltages”, “capacities_gravimetric”, “capacities_areal”, “capacities_absolute”, “capacities_gravimetric_split_constant_voltage”, “capacities_areal_split_constant_voltage”, “capacities_gravimetric_coulombic_efficiency”, “capacities_areal_coulombic_efficiency”, “capacities_absolute_coulombic_efficiency”, “fullcell_standard_gravimetric”, “fullcell_standard_areal”, “fullcell_standard_absolute”,
height – height of the plot (for plotly)
width – width of the plot (for plotly)
markers – use markers
title – title of the plot
x_range – limits for x-axis
y_range – limits for y-axis
ce_range – limits for coulombic efficiency (if present)
norm_range – limits for normalized capacity (if present)
cv_share_range – limits for cv share (if present)
split – split the plot
auto_convert_legend_labels – convert the legend labels to a nicer format.
interactive – use interactive plotting (plotly)
rangeslider – add a range slider to the x-axis (only for plotly)
share_y – share y-axis (only for plotly)
return_data – return the data used for plotting
verbose – print out some extra information to make it easier to find out what to plot next time
plotly_template – name of the plotly template to use
seaborn_palette – name of the seaborn palette to use
seaborn_style – name of the seaborn style to use
formation_cycles – number of formation cycles to show
show_formation – show formation cycles
show_legend – show the legend
x_axis_domain_formation_fraction – fraction of the x-axis domain for the formation cycles (default: 0.2)
column_separator – separation between columns when splitting the plot (only for plotly)
reset_losses – reset the losses to the first cycle (only for fullcell_standard plots)
link_capacity_scales – link the capacity scales (only for fullcell_standard plots)
fullcell_standard_normalization_type – normalization type for the fullcell standard plots (capacity retention) (divide, multiply, area, max, on-max, False) if normalization_type is on-max, the normalization factor is set to the maximum value of the capacity column if not provided if normalization_type is max, the normalization factor is set to the maximum value of the capacity column if not provided if normalization_type is shift-divide, the normalization is done by shifting the data by the normalization factor and then dividing by the normalization factor if normalization_type is divide, the normalization is done by dividing by the normalization factor and then multiplying by the scaler if normalization_type is multiply, the normalization is done by multiplying by the normalization factor and then multiplying by the scaler if normalization_type is area, the normalization is done by dividing by the area and then multiplying by the scaler if normalization_type is False, no normalization is done
fullcell_standard_normalization_factor – normalization factor for the fullcell standard plots
fullcell_standard_normalization_scaler – scaler for the fullcell standard plots
parameter] (seaborn_[update line) – additional parameters for the plotly traces (e.g. use plotly_marker_size=10 for updating the marker_size to 10)
parameter] – additional parameters for the seaborn lines (not many options available yet) (e.g. use seaborn_marker_size=10 for updating the marker_size to 10)
seaborn_line_hooks – list of functions to hook into the seaborn lines (e.g. to update the marker_size)
**kwargs – includes additional parameters for the plotting backend (not properly documented yet).

Returns:

Hint

If you want to modify the non-interactive (matplotlib) plot, you can get the axes from the returned figure by axes = figure.get_axes():

>> axes = figure.get_axes() >> ylabel = axes[0].get_ylabel() >> if “Coulombic” in ylabel: >> axes[0].set_ylabel(“C.E. (%)”) >> else: >> print(f”This is not the coulombic efficiency axis: {ylabel=}”)

cellpy.utils.processor module#

func(filename)[source]#

cellpy.utils package

Contents

cellpy.utils package#

Subpackages#

Submodules#

cellpy.utils.batch module#

cellpy.utils.collectors module#

cellpy.utils.diagnostics module#

cellpy.utils.easyplot module#

cellpy.utils.example_data module#

cellpy.utils.helpers module#

cellpy.utils.ica module#

cellpy.utils.live module#

cellpy.utils.ocv_rlx module#

cellpy.utils.plotutils module#

cellpy.utils.processor module#

Module contents#