cellpy.utils.helpers#
Module Contents#
Functions#
|
Adds areal capacity to the summary. |
|
Adds C-rates to the step table data frame. |
|
Add normalized capacity to the summary. |
|
Adds normalized cycles to the summary data frame. |
|
Helper function for concat_summaries. |
|
Merge all summaries in a batch into a gigantic summary data frame. |
|
Merge all summaries in a batch into a gigantic summary data frame. |
|
Helper function for concat_summaries. |
|
Adds a rate column to the dataframe (steps). |
Filter cells based on some criteria. |
|
|
Helper function for concat_summaries. |
|
Load a raw data file and save it as cellpy-file. |
create an empty CellpyCell object. |
|
|
Remove last rows after given cycle number |
|
Remove last rows after given cycle number |
|
Remove rows with supplied indexes (where the indexes typically are cycle-indexes). |
Remove outliers with missing neighbours. |
|
|
Remove outliers based highest and lowest allowed value |
|
Removes outliers based on neighbours |
|
Remove outliers based on z-score. |
|
Select only cycles charged or discharged with a given rate. |
|
Update the path in the pages (batch) from one type of OS to another. |
|
Cut all cycles after a given cycle index number. |
|
Cut all cycles before a given cycle index number. |
|
Remove outliers from a batch object. |
Attributes#
- 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_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.
- collect_frames(frames, group_it: bool, hdr_norm_cycle: str, keys: list, normalize_cycles: bool)[source]#
Helper function for concat_summaries.
- concat_summaries(b: cellpy.utils.batch.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) pandas.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 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.
- Returns:
pandas.DataFrame
- concatenate_summaries(b: cellpy.utils.batch.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) pandas.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.
- 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.
- 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)
- 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)[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: cellpy.utils.batch.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