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 (prms.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 prms.Paths.outdatadir and/or the batch-file-directory (prms.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 prms.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.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.

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

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#

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#