cellpy.utils.collectors#
Collectors are used for simplifying plotting and exporting batch objects.
Module Contents#
Classes#
Update both the collected data and the plot(s). |
|
Create a collection of capacity plots. |
|
Create a collection of ica (dQ/dV) plots. |
|
Collects and shows summaries. |
Functions#
|
Collects cycles from all the cells in the batch object. |
|
Plot charge-discharge curves. |
|
Perform histogram equalization on a numpy array. |
|
Collects ica (dQ/dV) curves from all the cells in the batch object. |
|
Plot charge-discharge curves. |
|
Replace legend labels with cell names in plotly plots. |
|
Load data from hdf5 file. |
|
Load figure from file. |
|
|
|
Load plotly figure from file. |
Create a new manager for a matplotlib figure. |
|
|
Generator that picks a cell from the batch object, yields its label and the cell itself. |
|
Remove markers from a plotly trace. |
|
|
|
Create a plot made up of sequences of data (voltage curves, dQ/dV, etc). |
|
Create a spread plot (error-bands instead of error-bars). |
|
Collects summaries using cellpy.utils.helpers.concat_summaries. |
|
Plot summaries (value vs cycle number). |
|
Replace y-axis label in matplotlib plots. |
Attributes#
- class BatchCollector(b, data_collector, plotter, collector_name=None, name=None, nick=None, autorun=True, backend='plotly', elevated_data_collector_arguments=None, elevated_plotter_arguments=None, data_collector_arguments: dict = None, plotter_arguments: dict = None, experimental: bool = False, **kwargs)[source]#
Update both the collected data and the plot(s).
- Parameters:
b (cellpy.utils.Batch) – the batch object.
data_collector (callable) – method that collects the data.
plotter (callable) – method that crates the plots.
collector_name (str) – name of collector.
name (str or bool) – name used for auto-generating filenames etc.
autorun (bool) – run collector and plotter immediately if True.
use_templates (bool) – also apply template(s) in autorun mode if True.
backend (str) – name of plotting backend to use (“plotly” or “matplotlib”).
elevated_data_collector_arguments (dict) – arguments picked up by the child class’ initializer.
elevated_plotter_arguments (dict) – arguments picked up by the child class’ initializer.
data_collector_arguments (dict) – keyword arguments sent to the data collector.
plotter_arguments (dict) – keyword arguments sent to the plotter.
update_name (bool) – update the name (using automatic name generation) based on new settings.
**kwargs – set Collector attributes.
- reset_arguments(data_collector_arguments: dict = None, plotter_arguments: dict = None)[source]#
Reset the arguments to the defaults.
- Parameters:
data_collector_arguments (dict) – optional additional keyword arguments for the data collector.
plotter_arguments (dict) – optional additional keyword arguments for the plotter.
- save(serial_number=None)[source]#
Save to csv, hdf5 and image files.
- Parameters:
serial_number (int) – serial number to append to the filename.
- show(**kwargs)[source]#
Show the figure.
Note
If you are working in a Jupyter notebook and using a “matplotlib”-type backend, the figure will most likely be shown automatically when the figure is rendered. You should not need to use this method in that case, unless you want to show the figure one extra time.
Note
The
showmethod returns thefigureobject and if thebackendused does not provide automatic rendering in the editor / running environment you are using, you might have to issue the rendering yourself. For example, if you are using plotly and running it as a script in a typical command shell, you will have to issue.show()on the returnedfigureobject.- Parameters:
**kwargs – sent to the plotter.
- Returns:
Figure object
- to_csv(serial_number=None)[source]#
Save to csv file.
- Parameters:
serial_number (int) – serial number to append to the filename.
- to_hdf5(serial_number=None)[source]#
Save to hdf5 file.
- Parameters:
serial_number (int) – serial number to append to the filename.
- to_image_files(serial_number=None)[source]#
Save to image files (png, svg, json).
Notes
This method requires
kaleidofor the plotly backend.Notes
Exporting to json is only applicable for the plotly backend.
- Parameters:
serial_number (int) – serial number to append to the filename.
- update(data_collector_arguments: dict = None, plotter_arguments: dict = None, reset: bool = False, update_data: bool = False, update_name: bool = False, update_plot: bool = True)[source]#
Update both the collected data and the plot(s).
- Parameters:
data_collector_arguments (dict) – keyword arguments sent to the data collector.
plotter_arguments (dict) – keyword arguments sent to the plotter.
reset (bool) – reset the arguments first.
update_data (bool) – update the data before updating the plot even if data has been collected before.
update_name (bool) – update the name (using automatic name generation) based on new settings.
update_plot (bool) – update the plot.
- class BatchCyclesCollector(b, plot_type='fig_pr_cell', collector_type='back-and-forth', cycles=None, max_cycle=None, rate=None, rate_on=None, rate_std=None, rate_agg=None, inverse=False, label_mapper=None, backend='plotly', cycles_to_plot=None, width=None, palette=None, show_legend=None, legend_position=None, fig_title=None, cols=None, group_legend_muting=True, *args, **kwargs)[source]#
Bases:
BatchCollector
Create a collection of capacity plots.
- Parameters:
b – cellpy batch object
plot_type (str) – either ‘fig_pr_cell’ or ‘fig_pr_cycle’
backend (str) – what plotting backend to use (currently only ‘plotly’ is supported)
collector_type (str) –
how the curves are given
”back-and-forth” - standard back and forth; discharge (or charge) reversed from where charge (or discharge) ends.
”forth” - discharge (or charge) continues along x-axis.
”forth-and-forth” - discharge (or charge) also starts at 0.
data_collector_arguments (dict)
plotter_arguments (dict)
cycles (list) – select these cycles (elevated data collector argument).
max_cycle (int) – drop all cycles above this value (elevated data collector argument).
rate (float) – filter on rate (C-rate) (elevated data collector argument).
rate_on (str or list of str) – only select cycles if based on the rate of this step-type (e.g. on=”charge”) (elevated data collector argument).
rate_std (float) – allow for this inaccuracy when selecting cycles based on rate (elevated data collector argument).
rate_agg (str) – how to aggregate the rate (e.g. “mean”, “max”, “min”, “first”, “last”) (elevated data collector argument).
inverse (bool) – select steps that do not have the given C-rate (elevated data collector argument).
label_mapper (callable or dict) – function (or dict) that changes the cell names (elevated data collector argument). The dictionary must have the cell labels as given in the journal.pages index and new label as values. Similarly, if it is a function it takes the cell label as input and returns the new label. Remark! No check are performed to ensure that the new cell labels are unique.
cycles_to_plot (int) – plot only these cycles (elevated plotter argument).
width (float) – width of plot (elevated plotter argument).
legend_position (str) – position of the legend (elevated plotter argument).
show_legend (bool) – set to False if you don’t want to show legend (elevated plotter argument).
fig_title (str) – title (will be put above the figure) (elevated plotter argument).
palette (str) – color-map to use (elevated plotter argument).
cols (int) – number of columns (elevated plotter argument).
- class BatchICACollector(b, plot_type='fig_pr_cell', cycles=None, max_cycle=None, rate=None, rate_on=None, rate_std=None, rate_agg=None, inverse=False, label_mapper=None, backend='plotly', cycles_to_plot=None, width=None, palette=None, show_legend=None, legend_position=None, fig_title=None, cols=None, group_legend_muting=True, *args, **kwargs)[source]#
Bases:
BatchCollector
Create a collection of ica (dQ/dV) plots.
- Parameters:
b – cellpy batch object
plot_type (str) – either ‘fig_pr_cell’ or ‘fig_pr_cycle’
backend (str) – what plotting backend to use (currently only ‘plotly’ is supported)
cycles (list) – select these cycles (elevated data collector argument).
max_cycle (int) – drop all cycles above this value (elevated data collector argument).
rate (float) – filter on rate (C-rate) (elevated data collector argument).
rate_on (str or list of str) – only select cycles if based on the rate of this step-type (e.g. on=”charge”) (elevated data collector argument).
rate_std (float) – allow for this inaccuracy when selecting cycles based on rate (elevated data collector argument).
rate_agg (str) – how to aggregate the rate (e.g. “mean”, “max”, “min”, “first”, “last”) (elevated data collector argument).
inverse (bool) – select steps that do not have the given C-rate (elevated data collector argument).
label_mapper (callable or dict) – function (or dict) that changes the cell names (elevated data collector argument). The dictionary must have the cell labels as given in the journal.pages index and new label as values. Similarly, if it is a function it takes the cell label as input and returns the new label. Remark! No check are performed to ensure that the new cell labels are unique.
cycles_to_plot (int) – plot points if True (elevated plotter argument).
width (float) – width of plot (elevated plotter argument).
palette (str) – color-map to use (elevated plotter argument).
legend_position (str) – position of the legend (elevated plotter argument).
show_legend (bool) – set to False if you don’t want to show legend (elevated plotter argument).
fig_title (str) – title (will be put above the figure) (elevated plotter argument).
cols (int) – number of columns (elevated plotter argument).
group_legend_muting (bool) – if True, the legend will be interactive (elevated plotter argument).
- class BatchSummaryCollector(b, max_cycle: int = None, rate=None, on=None, columns=None, column_names=None, normalize_capacity_on=None, scale_by=None, nom_cap=None, normalize_cycles=None, group_it=None, rate_std=None, rate_column=None, inverse=None, inverted: bool = None, key_index_bounds=None, backend: str = 'plotly', title: str = None, markers: bool = None, line: bool = None, width: int = None, height: int = None, legend_title: str = None, marker_size: int = None, cmap=None, spread: bool = None, fig_title: str = None, *args, **kwargs)[source]#
Bases:
BatchCollector
Collects and shows summaries.
- Parameters:
backend (str) – what plotting backend to use (currently only ‘plotly’ is supported)
max_cycle (int) – drop all cycles above this value (elevated data collector argument).
rate (float) – filter on rate (C-rate) (elevated data collector argument).
on (str or list of str) – only select cycles if based on the rate of this step-type (e.g. on=”charge”). (elevated data collector argument).
columns (list) – selected column(s) (using cellpy attribute name). Defaults to “charge_capacity_gravimetric”. (elevated data collector argument).
column_names (list) – selected column(s) (using exact column name) (elevated data collector argument)
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) (elevated data collector argument)
scale_by (float or str) – scale the normalized data with nominal capacity if “nom_cap”, or given value (defaults to one) (elevated data collector argument).
nom_cap (float) – nominal capacity of the cell (elevated data collector argument)
normalize_cycles (bool) – perform a normalization of the cycle numbers (also called equivalent cycle index) (elevated data collector argument).
group_it (bool) – if True, average pr group (elevated data collector argument).
rate_std (float) – allow for this inaccuracy when selecting cycles based on rate (elevated data collector argument)
rate_column (str) – name of the column containing the C-rates (elevated data collector argument).
inverse (bool) – select steps that do not have the given C-rate (elevated data collector argument).
inverted (bool) – select cycles that do not have the steps filtered by given C-rate (elevated data collector argument).
key_index_bounds (list) – used when creating a common label for the cells in a group (when group_it is set to True) by splitting and combining from key_index_bound[0] to key_index_bound[1]. For example, if your cells are called “cell_01_01” and “cell_01_02” and you set key_index_bounds=[0, 2], the common label will be “cell_01”. Or if they are called “20230101_cell_01_01_01” and “20230101_cell_01_01_02” and you set key_index_bounds=[1, 3], the common label will be “cell_01_01” (elevated data collector argument).
markers (bool) – plot points if True (elevated plotter argument).
line (bool) – plot line if True (elevated plotter argument).
width – width of plot (elevated plotter argument).
height – height of plot (elevated plotter argument).
legend_title – title to put over the legend (elevated plotter argument).
marker_size – size of the markers used (elevated plotter argument).
cmap – color-map to use (elevated plotter argument).
spread (bool) – plot error-bands instead of error-bars if True (elevated plotter argument).
fig_title (str) – title of the figure (elevated plotter argument).
- cycles_collector(b, cycles=None, rate=None, rate_on=None, rate_std=None, rate_agg='first', inverse=False, interpolated=True, number_of_points=100, max_cycle=50, abort_on_missing=False, method='back-and-forth', label_mapper=None, mode='gravimetric')[source]#
Collects cycles from all the cells in the batch object.
- Parameters:
b – cellpy batch object
cycles – list of cycle numbers to collect
rate – filter on rate (C-rate)
rate_on – only select cycles if based on the rate of this step-type (e.g. on=”charge”).
rate_std – allow for this inaccuracy when selecting cycles based on rate
rate_agg – how to aggregate the rate (e.g. “mean”, “max”, “min”, “first”, “last”)
inverse – select steps that do not have the given C-rate.
interpolated – if True, interpolate the data
number_of_points – number of points to interpolate to
max_cycle – drop all cycles above this value
abort_on_missing – if True, abort if a cell is empty
method – how the voltage curves are given (back-and-forth, forth, forth-and-forth)
label_mapper – function (or dict) that changes the cell names.
mode (string) – ‘gravimetric’, ‘areal’, ‘volumetric’ or ‘absolute’.
- Returns:
collected data
- Return type:
pd.DataFrame
- cycles_plotter(collected_curves, cycles_to_plot=None, backend='plotly', method='fig_pr_cell', x_unit='mAh/g', y_unit='V', **kwargs)[source]#
Plot charge-discharge curves.
- Parameters:
collected_curves (pd.DataFrame) – collected data in long format.
cycles_to_plot (list) – cycles to plot
backend (str) – what backend to use.
method (str) – ‘fig_pr_cell’ or ‘fig_pr_cycle’.
x_unit (str) – unit for x-axis.
y_unit (str) – unit for y-axis.
**kwargs – consumed first in current function, rest sent to backend in sequence_plotter.
- Returns:
styled figure object
- histogram_equalization(image: numpy.array) numpy.array[source]#
Perform histogram equalization on a numpy array.
- ica_collector(b, cycles=None, rate=None, rate_on=None, rate_std=None, rate_agg='first', inverse=False, voltage_resolution=0.005, max_cycle=50, abort_on_missing=False, label_direction=True, number_of_points=None, label_mapper=None, **kwargs)[source]#
Collects ica (dQ/dV) curves from all the cells in the batch object.
- Parameters:
b – cellpy batch object
cycles – list of cycle numbers to collect
rate – filter on rate (C-rate)
rate_on – only select cycles if based on the rate of this step-type (e.g. on=”charge”).
rate_std – allow for this inaccuracy when selecting cycles based on rate
rate_agg – how to aggregate the rate (e.g. “mean”, “max”, “min”, “first”, “last”)
inverse – select steps that do not have the given C-rate.
voltage_resolution – smoothing of the voltage curve
number_of_points – number of points to interpolate to
max_cycle – drop all cycles above this value
abort_on_missing – if True, abort if a cell is empty
label_direction – how the voltage curves are given (back-and-forth, forth, forth-and-forth)
label_mapper – function (or dict) that changes the cell names.
**kwargs – passed on to ica.dqdv
- Returns:
collected data
- Return type:
pd.DataFrame
- ica_plotter(collected_curves, cycles_to_plot=None, backend='plotly', method='fig_pr_cell', direction='charge', **kwargs)[source]#
Plot charge-discharge curves.
- Parameters:
collected_curves (pd.DataFrame) – collected data in long format.
cycles_to_plot (list) – cycles to plot
backend (str) – what backend to use.
method (str) – ‘fig_pr_cell’ or ‘fig_pr_cycle’ or ‘film’.
direction (str) – ‘charge’ or ‘discharge’.
**kwargs – consumed first in current function, rest sent to backend in sequence_plotter.
- Returns:
styled figure object
- legend_replacer(trace, df, group_legends=True)[source]#
Replace legend labels with cell names in plotly plots.
- pick_named_cell(b, label_mapper=None)[source]#
Generator that picks a cell from the batch object, yields its label and the cell itself.
- Parameters:
b (cellpy.batch object) – your batch object
label_mapper (callable or dict) – function (or dict) that changes the cell names. The dictionary must have the cell labels as given in the journal.pages index and new label as values. Similarly, if it is a function it takes the cell label as input and returns the new label. Remark! No check are performed to ensure that the new cell labels are unique.
- Yields:
label, group, subgroup, cell
Example
- def my_mapper(n):
return “_”.join(n.split(“_”)[1:-1])
# outputs “nnn_x” etc., if cell-names are of the form “date_nnn_x_y”: for label, group, subgroup, cell in pick_named_cell(b, label_mapper=my_mapper):
print(label)
- sequence_plotter(collected_curves: pandas.DataFrame, x: str = 'capacity', y: str = 'voltage', z: str = 'cycle', g: str = 'cell', standard_deviation: str = None, group: str = 'group', subgroup: str = 'sub_group', x_label: str = 'Capacity', x_unit: str = 'mAh/g', y_label: str = 'Voltage', y_unit: str = 'V', z_label: str = 'Cycle', z_unit: str = 'n.', y_label_mapper: dict = None, nbinsx: int = 100, histfunc: str = 'avg', histscale: str = 'abs-log', direction: str = 'charge', direction_col: str = 'direction', method: str = 'fig_pr_cell', markers: bool = False, group_cells: bool = True, group_legend_muting: bool = True, backend: str = 'plotly', cycles: list = None, facetplot: bool = False, cols: int = 3, palette_discrete: str = None, palette_continuous: str = 'Viridis', palette_range: tuple = None, height: float = None, width: float = None, spread: bool = False, **kwargs) Any[source]#
Create a plot made up of sequences of data (voltage curves, dQ/dV, etc).
This method contains the “common” operations done for all the sequence plots, currently supporting filtering out the specific cycles, selecting either dividing into subplots by cell or by cycle, and creating the (most basic) figure object.
- Parameters:
collected_curves (pd.DataFrame) – collected data in long format.
x (str) – column name for x-values.
y (str) – column name for y-values.
z (str) – if method is ‘fig_pr_cell’, column name for color (legend), else for subplot.
g (str) – if method is ‘fig_pr_cell’, column name for subplot, else for color.
standard_deviation – str = standard deviation column (skipped if None).
group (str) – column name for group.
subgroup (str) – column name for subgroup.
x_label (str) – x-label.
x_unit (str) – x-unit (will be put in parentheses after the label).
y_label (str) – y-label.
y_unit (str) – y-unit (will be put in parentheses after the label).
z_label (str) – z-label.
z_unit (str) – z-unit (will be put in parentheses after the label).
y_label_mapper (dict) – map the y-labels to something else.
nbinsx (int) – number of bins to use in interpolations.
histfunc (str) – aggregation method.
histscale (str) – used for scaling the z-values for 2D array plots (heatmaps and similar).
direction (str) – “charge”, “discharge”, or “both”.
direction_col (str) – name of columns containing information about direction (“charge” or “discharge”).
method – ‘fig_pr_cell’ or ‘fig_pr_cycle’.
markers – set to True if you want markers.
group_cells (bool) – give each cell within a group same color.
group_legend_muting (bool) – if True, you can click on the legend to mute the whole group (only for plotly).
backend (str) – what backend to use.
cycles – what cycles to include in the plot.
palette_discrete – palette to use for discrete color mapping.
palette_continuous – palette to use for continuous color mapping.
palette_range (tuple) – range of palette to use for continuous color mapping (from 0 to 1).
facetplot (bool) – square layout with group horizontally and subgroup vertically.
cols (int) – number of columns for layout.
height (int) – plot height.
width (int) – plot width.
spread (bool) – plot error-bands instead of error-bars if True.
**kwargs – sent to backend (if backend == “plotly”, it will be sent to plotly.express etc.)
- Returns:
figure object
- spread_plot(curves, plotly_arguments, **kwargs)[source]#
Create a spread plot (error-bands instead of error-bars).
- summary_collector(*args, **kwargs)[source]#
Collects summaries using cellpy.utils.helpers.concat_summaries.
- summary_plotter(collected_curves, cycles_to_plot=None, backend='plotly', **kwargs)[source]#
Plot summaries (value vs cycle number).
Assuming data as pandas.DataFrame with either 1) long format (where variables, for example charge capacity, are in the column “variable”) or 2) mixed long and wide format where the variables are own columns.