Utils¶

Create a Batch from a journal file

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 –

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

Returns an initialized instance of the Batch class.

Parameters:

• empty (bool, default: False ) –

  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.

Other Parameters:

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

Returns an initialized instance of the Batch class.

Parameters:

• empty (bool, default: False ) –

  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.

Other Parameters:

• 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 through all journals in given folder.

Parameters:

• folder (str or Path) –

  folder containing the journal files.

• extension (str, default: '.json' ) –

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

• glob_pattern (str, default: None ) –

  optional glob pattern.

• **kwargs –

  keyword arguments passed to batch.process_batch.

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, default: None ) –

  batch column identifier (only used for loading from db with simple_db_reader)

• allow_from_journal (bool, default: True ) –

  if True, the journal file will be loaded if it exists

• allow_using_backup_journal (bool, default: False ) –

  if True, the backup journal file will be used if the journal file does not exist

• force_reload (bool, default: False ) –

  if True, the batch will be reloaded even if the journal file exists

• drop_bad_cells (bool, default: True ) –

  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, default: 'default' ) –

  reader to use (defaults to "default" as given in the config-file or prm-class).

• reader_path (str, default: None ) –

  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 Path, default: None ) –

  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

Other Parameters:

• db_reader (str) –

  data-base reader to use (defaults to "default" as given in the config-file or prm-class).

• frame (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 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 a journal file.

Parameters:

• journal_file (str) –

  path to journal file.

• **kwargs –

  sent to Journal.from_file

Returns:

• –

  journal

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:

• DataFrame –

  pandas.DataFrame

Returns an empty instance of the Batch class.

Examples:

>>> empty_batch = naked()

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

Examples:

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

Parameters:

• *args –

  file_name or name and project (both string)

Other Parameters:

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

• Batch –

  cellpy.batch.Batch object

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)

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)

Show raw data together with step and cycle information.

Draws through prepare → spec → render (#647).

Parameters:

• cell –

  cellpy object

• cycle (int or list or tuple, default: None ) –

  cycle(s) to select (must be int for matplotlib)

• get_axes (bool, default: False ) –

  return axes (for matplotlib) or figure (for plotly)

• backend (str, default: None ) –

  "plotly" (default) or "matplotlib".

• interactive (bool, default: None ) –

  Deprecated alias for backend selection (True→plotly, False→matplotlib; removal 2.1).

• t_unit (str, default: 'hours' ) –

  unit for x-axis (default: "hours")

• v_unit (str, default: 'V' ) –

  unit for y-axis (default: "V")

• i_unit (str, default: 'mA' ) –

  unit for current (default: "mA")

• **kwargs –

  parameters specific to plotting backend.

Returns:

• –

  matplotlib.axes or None (or a figure when get_axes / backend semantics require it)

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.

Draws through prepare → spec → render (#646).

Parameters:

• c –

  cellpy object containing the data to plot.

• cycles (list, default: None ) –

  List of cycle numbers to plot. If None, all cycles are plotted.

• inter_cycle_shift (bool, default: True ) –

  Whether to shift the cycles by one. Default is True.

• cycle_mode (str, default: None ) –

  Mode for the test (anode or other). Default is None (i.e. use the cellpy cell object's cycle_mode).

• formation_cycles (int, default: 3 ) –

  Number of formation cycles to highlight. Default is 3.

• show_formation (bool, default: True ) –

  Whether to show formation cycles. Default is True.

• mode (str, default: 'gravimetric' ) –

  Mode for capacity ('gravimetric', 'areal', etc.). Default is 'gravimetric'.

• method (str, default: 'forth-and-forth' ) –

  Method for interpolation. Default is 'forth-and-forth'.

• interpolated (bool, default: True ) –

  Whether to interpolate the data. Default is True.

• number_of_points (int, default: 200 ) –

  Number of points for interpolation. Default is 200.

• colormap (str, default: 'Blues_r' ) –

  Colormap for the cycles. Default is 'Blues_r'.

• formation_colormap (str, default: 'autumn' ) –

  Colormap for the formation cycles. Default is 'autumn'.

• cut_colorbar (bool, default: True ) –

  Whether to cut the colorbar. Default is True.

• title (str, default: None ) –

  Title of the plot. If None, the cell name is used.

• figsize (tuple, default: (6, 4) ) –

  Size of the figure for matplotlib. Default is (6, 4).

• x_range (list, default: None ) –

  Limits for the x-axis.

• y_range (list, default: None ) –

  Limits for the y-axis.

• xlim (list, default: None ) –

  Deprecated alias for x_range (removal 2.1).

• ylim (list, default: None ) –

  Deprecated alias for y_range (removal 2.1).

• backend (str, default: None ) –

  "plotly" (default) or "matplotlib".

• interactive (bool, default: None ) –

  Deprecated alias for backend selection (True→plotly, False→matplotlib; removal 2.1).

• return_figure (bool, default: None ) –

  Whether to return the figure object. Default is True for matplotlib and False for plotly (fig.show()).

• width (int, default: 800 ) –

  Width of the figure for Plotly. Default is 800.

• height (int, default: 600 ) –

  Height of the figure for Plotly. Default is 600.

• marker_size (int, default: 5 ) –

  Size of the markers for Plotly. Default is 5.

• formation_line_color (str, default: 'rgba(152, 0, 0, .8)' ) –

  Color for the formation cycle lines in Plotly. Default is 'rgba(152, 0, 0, .8)'.

• force_colorbar (bool, default: False ) –

  Whether to force the colorbar to be shown. Default is False.

• force_nonbar (bool, default: False ) –

  Whether to force the colorbar to be hidden. Default is False.

• plotly_template (str, default: None ) –

  Plotly template to use (uses default template if None).

• seaborn_palette (str, default: 'deep' ) –

  name of the seaborn palette to use (only if seaborn is available).

• seaborn_style (str, default: 'dark' ) –

  name of the seaborn style to use (only if seaborn is available).

• return_data (bool, default: False ) –

  Whether to return the data used for the plot. Default is False.

• **kwargs –

  Additional keyword arguments for the plotting backend.

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.

Plot differential voltage analysis (dV/dQ vs capacity).

Draws through prepare → spec → render (#648). Data come from cellpy.ica.dvdq; both half-cycles are overlaid when direction="both" (plotly hover shows charge/discharge).

Parameters:

• cell –

  cellpy object.

• cycles –

  Cycle number or list (None = all).

• direction –

  "charge", "discharge", or "both".

• options –

  Optional IcaOptions (defaults to DVA-oriented options inside dvdq).

• backend (Optional[str], default: None ) –

  "plotly" (default) or "matplotlib".

• interactive (Optional[bool], default: None ) –

  Deprecated alias for backend selection (removal 2.1).

• title –

  Figure title.

• colormap –

  Cycle colour map.

• width, height –

  Plotly figure size.

• figsize –

  Matplotlib figure size.

• x_range, y_range –

  Optional axis ranges.

• plotly_template –

  Optional plotly template name.

• return_data –

  If True, return (figure, frame).

• **kwargs –

  Extra knobs (strict, cycle_mode, number_of_points, and individual IcaOptions field overrides).

Returns:

• –

  Plotly or matplotlib figure (or (figure, frame) when return_data).

Plot incremental capacity (dQ/dV vs voltage).

Draws through prepare → spec → render (#648). Data come from cellpy.ica.dqdv; both half-cycles are overlaid when direction="both" (plotly hover shows charge/discharge).

Parameters:

• cell –

  cellpy object.

• cycles –

  Cycle number or list (None = all).

• direction –

  "charge", "discharge", or "both".

• options –

  Optional IcaOptions.

• backend (Optional[str], default: None ) –

  "plotly" (default) or "matplotlib".

• interactive (Optional[bool], default: None ) –

  Deprecated alias for backend selection (removal 2.1).

• title –

  Figure title.

• colormap –

  Cycle colour map.

• width, height –

  Plotly figure size.

• figsize –

  Matplotlib figure size.

• x_range, y_range –

  Optional axis ranges.

• plotly_template –

  Optional plotly template name.

• return_data –

  If True, return (figure, frame).

• **kwargs –

  Extra knobs (strict, cycle_mode, number_of_points, and individual IcaOptions field overrides).

Returns:

• –

  Plotly or matplotlib figure (or (figure, frame) when return_data).

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 the summary data into CV and non-CV steps.

Parameters:

• c –

  cellpy object

• x (str) –

  x-axis column name

• column_set (list) –

  names of columns to include

• split (bool, default: False ) –

  add additional column that can be used to split the data when plotting.

• var_name (str, default: 'variable' ) –

  name of the variable column after melting

• value_name (str, default: 'value' ) –

  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)

Plot raw data.

Draws through prepare → spec → render (#647).

Parameters:

• cell –

  cellpy object

• y (str or list, default: None ) –

  y-axis column

• y_label (str or list, default: None ) –

  label for y-axis

• x (str, default: None ) –

  x-axis column

• x_label (str, default: None ) –

  label for x-axis

• title (str, default: None ) –

  title of the plot

• backend (str, default: None ) –

  "plotly" (default) or "matplotlib".

• interactive (bool, default: None ) –

  Deprecated alias for backend selection (True→plotly, False→matplotlib; removal 2.1).

• plot_type (str, default: 'voltage-current' ) –

  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, default: True ) –

  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 to image files (png, svg, json/pickle).

Parameters:

• figure (fig - object) –

  The figure to save.

• name (Path or str, default: 'my_figure' ) –

  The path of the file (without extension).

• scale (float, default: 3.0 ) –

  The scale of the image.

• dpi (int, default: 300 ) –

  The dpi of the image.

• backend (str, default: 'plotly' ) –

  The backend to use (plotly or seaborn/matplotlib).

• formats (list, default: None ) –

  The formats to save (default: ["png", "svg", "json", "pickle"]).

Set the default plotly template.

Create a summary plot.

Parameters:

• c –

  cellpy object

• x (Optional[str], default: None ) –

  x-axis column (default: 'cycle_index')

• y (str, default: 'capacities_gravimetric_coulombic_efficiency' ) –

  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 (Optional[int], default: None ) –

  height of the plot (for plotly)

• width (int, default: 900 ) –

  width of the plot (for plotly)

• markers (bool, default: True ) –

  use markers

• title (Optional[str], default: None ) –

  title of the plot

• x_range (Optional[list], default: None ) –

  limits for x-axis

• y_range (Optional[list], default: None ) –

  limits for y-axis

• ce_range (Optional[list], default: None ) –

  limits for coulombic efficiency (if present)

• norm_range (Optional[list], default: None ) –

  limits for normalized capacity (if present)

• cv_share_range (Optional[list], default: None ) –

  limits for cv share (if present)

• split (bool, default: True ) –

  split the plot

• hover_columns (Optional[list], default: None ) –

  columns to show in the hover tooltip (only for plotly)

• auto_convert_legend_labels (bool, default: True ) –

  convert the legend labels to a nicer format.

• backend (Optional[str], default: None ) –

  plotting backend ("plotly" or "matplotlib"; default "plotly")

• interactive (Optional[bool], default: None ) –

  deprecated alias for backend selection (True → "plotly", False → "matplotlib"); removal 2.1

• rangeslider (bool, default: False ) –

  add a range slider to the x-axis (only for plotly)

• share_y (bool, default: False ) –

  share y-axis (only for plotly)

• return_data (bool, default: False ) –

  return the data used for plotting

• verbose (bool, default: False ) –

  print out some extra information to make it easier to find out what to plot next time

• plotly_template (Optional[str], default: None ) –

  name of the plotly template to use

• seaborn_palette (str, default: 'deep' ) –

  name of the seaborn palette to use (matplotlib backend)

• seaborn_style (str, default: 'dark' ) –

  name of the seaborn style to use (matplotlib backend)

• formation_cycles (int, default: 3 ) –

  number of formation cycles to show

• show_formation (bool, default: True ) –

  show formation cycles

• show_legend (bool, default: True ) –

  show the legend

• x_axis_domain_formation_fraction (float, default: 0.2 ) –

  fraction of the x-axis domain for the formation cycles (default: 0.2)

• column_separator (float, default: 0.01 ) –

  separation between columns when splitting the plot (only for plotly)

• reset_losses (bool, default: True ) –

  reset the losses to the first cycle (only for fullcell_standard plots)

• link_capacity_scales (bool, default: False ) –

  link the capacity scales (only for fullcell_standard plots)

• fullcell_standard_normalization_type (str, default: 'max' ) –

  normalization type for the fullcell standard plots (capacity retention) (divide, multiply, area, max, on-max, False)

• fullcell_standard_normalization_factor (Optional[float], default: None ) –

  normalization factor for the fullcell standard plots

• fullcell_standard_normalization_scaler (float, default: 1.0 ) –

  scaler for the fullcell standard plots

• fullcell_standard_normalization_cycle_numbers (Optional[list[int]], default: None ) –

  cycle numbers to use for normalization (only for fullcell_standard plots)

• seaborn_line_hooks (Optional[list[tuple[str, list, dict]]], default: None ) –

  list of functions to hook into the seaborn lines (e.g. to update the marker_size)

• filters (Optional[dict], default: None ) –

  optional dict forwarded to :func: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 :func:cellpy.filters.filter_summary for range semantics.

• nominal_capacity (Optional[float], default: None ) –

  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[Union[str, tuple, list]], default: None ) –

  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:

• Any –

  if return_data is True, returns a tuple with the figure and the data used for plotting.

• Any –

  Otherwise, it returns only the figure. With backend="plotly" the figure is a

• Any –

  plotly figure; with backend="matplotlib" 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 matplotlib backend (seaborn styling), e.g. for an SVG export from a script::

>>> fig = summary_plot(c, y="capacities_gravimetric", backend="matplotlib")
>>> 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 :meth: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))

Deprecated. Use summary_plot.

The 1 400-line implementation that used to live here was broken, not merely redundant: its first statement unpacked the return value of SummaryPlotInfo._create_col_info, which stores its results as attributes and returns None — so every call raised TypeError regardless of the cell or the runtime (#567). Nothing in the repo called it, and nothing outside it could have called it successfully either.

Delegates to summary_plot, which draws the same figures through the builder pipeline. Removal in 2.1.

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 points from the ocvrlx steps.

Parameters:

• cellpydata –

  CellpyData-object

• cycles –

  list of cycle numbers to process (optional)

• cell_label (str, default: None ) –

  optional, will be added to the frame if given

• include_times (bool, default: True ) –

  include additional information including times.

• selection_method (martin | fixed_times, default: 'martin' ) –

  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), default: '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)

Adds areal capacity to the summary.

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, default: None ) –

  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, default: None ) –

  name of the new column. Uses the name defined in cellpy.parameters.internal_settings as default.

Returns:

• –

  data object.

Add columns for CV steps.

Add normalized capacity to the summary.

Parameters:

• cell (CellpyCell) –

  cell to add normalized capacity to.

• norm_cycles (list of ints, default: None ) –

  the cycles that will be used to find the normalization factor from (averaging their capacity)

• individual_normalization (bool, default: False ) –

  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, default: 1.0 ) –

  scale of normalization (default is 1.0).

Returns:

• –

  cell (CellpyData) with added normalization capacity columns in

• –

  the summary.

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

  data summary

• nom_cap (float) –

  nominal capacity to use when normalizing.

• column_name (str, default: None ) –

  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.

Helper function for concat_summaries.

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, default: None ) –

  drop all cycles above this value.

• rate (float, default: None ) –

  filter on rate (C-rate)

• on (str or list of str, default: 'charge' ) –

  only select cycles if based on the rate of this step-type (e.g. on="charge").

• columns (list, default: None ) –

  selected column(s) (using cellpy attribute name) [defaults to "charge_capacity_gravimetric"]

• column_names (list, default: None ) –

  selected column(s) (using exact column name)

• normalize_capacity_on (list, default: None ) –

  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, default: None ) –

  scale the normalized data with nominal capacity if "nom_cap", or given value (defaults to one).

• nom_cap (float, default: None ) –

  nominal capacity of the cell

• normalize_cycles (bool, default: False ) –

  perform a normalization of the cycle numbers (also called equivalent cycle index)

• group_it (bool, default: False ) –

  if True, average pr group.

• partition_by_cv (bool, default: False ) –

  if True, partition the data by cv_step.

• custom_group_labels (dict, default: None ) –

  dictionary of custom labels (key must be the group number/name).

• rate_std (float, default: None ) –

  allow for this inaccuracy when selecting cycles based on rate

• rate_column (str, default: None ) –

  name of the column containing the C-rates.

• inverse (bool, default: False ) –

  select steps that do not have the given C-rate.

• inverted (bool, default: False ) –

  select cycles that do not have the steps filtered by given C-rate.

• key_index_bounds (list, default: None ) –

  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 (DataFrame, default: None ) –

  alternative pages (journal) of the batch object (if not given, it will use the pages from the batch object).

• recalc_summary_kwargs (dict, default: None ) –

  keyword arguments to be used when recalculating the summary. If not given, it will not recalculate the summary.

• recalc_step_table_kwargs (dict, default: None ) –

  keyword arguments to be used when recalculating the step table. If not given, it will not recalculate the step table.

• only_selected (bool, default: False ) –

  only use the selected cells.

• experimental_feature_cell_selector (list, default: None ) –

  list of cell names to select.

• partition_by_cv (bool, default: False ) –

  if True, partition the data by cv_step.

• replace_inf_with_nan (bool, default: True ) –

  if True, replace inf with nan in the summary data.

• individual_summary_hooks (list, default: None ) –

  list of functions to be applied to the individual summary data.

• concatenated_summary_hooks (list, default: None ) –

  list of functions to be applied to the concatenated summary data (passed to the collect_frames function).

• drop_columns (list, default: None ) –

  list of columns to drop before concatenation.

• average_method (str, default: 'mean' ) –

  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, default: True ) –

  if True, replace values outside the range [low_limit, high_limit] with nan in the summary data.

• low_limit (float, default: -1000000.0 ) –

  lower limit for replacing extremes with nan if replace_extremes_with_nan is True.

• high_limit (float, default: 1000000.0 ) –

  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,**kwargs –

  additional arguments to be passed to the hooks.

Returns:

• DataFrame –

  pandas.DataFrame

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, default: None ) –

  drop all cycles above this value.

• rate (float, default: None ) –

  filter on rate (C-rate)

• on (str or list of str, default: 'charge' ) –

  only select cycles if based on the rate of this step-type (e.g. on="charge").

• columns (list, default: None ) –

  selected column(s) (using cellpy attribute name) [defaults to "charge_capacity_gravimetric"]

• column_names (list, default: None ) –

  selected column(s) (using exact column name)

• normalize_capacity_on (list, default: None ) –

  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, default: None ) –

  scale the normalized data with nominal capacity if "nom_cap", or given value (defaults to one).

• nom_cap (float, default: None ) –

  nominal capacity of the cell

• normalize_cycles (bool, default: False ) –

  perform a normalization of the cycle numbers (also called equivalent cycle index)

• group_it (bool, default: False ) –

  if True, average pr group.

• custom_group_labels (dict, default: None ) –

  dictionary of custom labels (key must be the group number/name).

• rate_std (float, default: None ) –

  allow for this inaccuracy when selecting cycles based on rate

• rate_column (str, default: None ) –

  name of the column containing the C-rates.

• inverse (bool, default: False ) –

  select steps that do not have the given C-rate.

• inverted (bool, default: False ) –

  select cycles that do not have the steps filtered by given C-rate.

• key_index_bounds (list, default: None ) –

  used when creating a common label for the cells by splitting and combining from key_index_bound[0] to key_index_bound[1].

Returns:

• DataFrame –

  pandas.DataFrame

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

  pages (journal) of the batch object. If the column "group_label" is present, it will be used to create the group name.

Adds a rate column to the dataframe (steps).

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.

Helper function for concat_summaries.

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

Parameters:

• mass (float, default: 1.0 ) –

  active material mass [mg].

• outdir (path, default: None ) –

  optional, path to directory for saving the hdf5-file.

• outfile (str, default: None ) –

  optional, name of hdf5-file.

• filename (str) –

  name of the resfile.

Returns:

• out_file_name ( str ) –

  name of saved 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).

Parameters:

• s (DataFrame) –

  cellpy summary to process

• indexes (list, default: None ) –

  list of indexes

• remove_last (bool, default: False ) –

  remove the last point

Returns:

• –

  pandas.DataFrame

Remove outliers with missing neighbours.

Parameters:

• s (DataFrame) –

  summary frame

• distance (float, default: 0.7 ) –

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

• filter_cols (list, default: None ) –

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

• freeze_indexes (list, default: None ) –

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

Returns:

• –

  filtered summary (pandas.DataFrame)

Returns:

Remove outliers based highest and lowest allowed value

Parameters:

• s (DataFrame) –

  summary frame

• low (float, default: 0.0 ) –

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

• high (float, default: 7000 ) –

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

• filter_cols (list, default: None ) –

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

• freeze_indexes (list, default: None ) –

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

Returns:

• –

  filtered summary (pandas.DataFrame)

Returns:

Removes outliers based on neighbours

Remove outliers based on z-score.

Parameters:

• s (DataFrame) –

  summary frame

• zscore_limit (int, default: 4 ) –

  remove outliers outside this z-score limit

• filter_cols (list, default: None ) –

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

• freeze_indexes (list, default: None ) –

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

Returns:

• –

  filtered summary (pandas.DataFrame)

Select only cycles charged or discharged with a given rate.

Parameters:

• rate (float, default: None ) –

  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, default: None ) –

  only select cycles if based on the rate of this step-type (e.g. on="charge").

• rate_std (float, default: None ) –

  allow for this inaccuracy in C-rate when selecting cycles

• rate_column (str, default: None ) –

  column header name of the rate column,

• inverse (bool, default: False ) –

  select steps that do not have the given C-rate.

• inverted (bool, default: False ) –

  select cycles that do not have the steps filtered by given C-rate.

• fix_index (bool, default: True ) –

  automatically set cycle indexes as the index for the summary dataframe if not already set.

Returns:

• –

  filtered summary (Pandas.DataFrame).

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)

Cut all cycles after a given cycle index number.

Parameters:

• b (batch object) –

  the batch object to perform the cut on.

• last (int or dict {cell_name –

  last index}): the last cycle index to keep (if dict: use individual last indexes for each cell).

• keep_old (bool, default: False ) –

  keep the original batch object and return a copy instead.

Returns:

• –

  batch object if keep_old is True, else None

Cut all cycles before a given cycle index number.

Parameters:

• b (batch object) –

  the batch object to perform the cut on.

• first (int or dict {cell_name –

  first index}): the first cycle index to keep (if dict: use individual first indexes for each cell).

• keep_old (bool, default: False ) –

  keep the original batch object and return a copy instead.

Returns:

• –

  batch object if keep_old is True, else None

Remove outliers from a batch object.

Parameters: