cellpy 2.0.0a3__tar.gz → 2.0.0a4__tar.gz

{cellpy-2.0.0a3 → cellpy-2.0.0a4}/HISTORY.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+* **Breaking:** `CellpyCell.get_cap` now returns native `cellpycore` curve
+  columns (#540, native-headers flip Stage 1): `voltage` → `potential` and
+  `cycle` → `cycle_num` (`capacity` / `direction` unchanged). All in-repo
+  consumers — `plotutils.cycles_plot`, the batch collectors, `ica`, and the
+  CSV/Excel exporters — are updated; user code that indexes the `get_cap`
+  frame directly must rename. See `docs/getting_started/migration_v1_to_v2.md`.
+
 * Removed the deprecated `cellpy.utils.easyplot` module (#544). It was
   deprecated since 1.1 with removal scheduled for 2.0; use
   `cellpy.utils.plotutils` and `cellpy.utils.collectors` instead. The module,

{cellpy-2.0.0a3 → cellpy-2.0.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cellpy
-Version: 2.0.0a3
+Version: 2.0.0a4
 Summary: Extract and manipulate data from battery data testers.
 Project-URL: Homepage, https://github.com/jepegit/cellpy
 Project-URL: Repository, https://github.com/jepegit/cellpy

{cellpy-2.0.0a3 → cellpy-2.0.0a4}/cellpy/exporters/tabular.py

@@ -23,9 +23,15 @@ import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from cellpycore.config import CurveCols
+
 from cellpy.exceptions import NoDataFound
 from cellpy.readers import externals
 
+# get_cap emits native CurveCols names (#540): potential/cycle_num, not
+# voltage/cycle.
+_CCOLS = CurveCols()
+
 if TYPE_CHECKING:
     from cellpy.readers.cellreader import CellpyCell
 
@@ -74,8 +80,8 @@ def export_cycles(
             if df.empty:
                 logging.debug("NoneType from get_cap")
             else:
-                c = df["capacity"]
-                v = df["voltage"]
+                c = df[_CCOLS.capacity]
+                v = df[_CCOLS.potential]
 
                 _last = c.iat[-1]
                 _first = c.iat[0]

{cellpy-2.0.0a3 → cellpy-2.0.0a4}/cellpy/readers/capacity_curves.py

@@ -13,12 +13,20 @@ import logging
 import warnings
 from typing import TYPE_CHECKING
 
+from cellpycore.config import CurveCols
+
 import cellpy.config as config
 
 from . import externals as externals
 from cellpy.readers import data_structures as ds
 from cellpy.exceptions import NullData
 
+# Native curve-frame column names (cellpycore #118). get_cap and the
+# single-branch charge/discharge extractors emit these unconditionally on the
+# v2 line (#540): potential/cycle_num replace the legacy voltage/cycle;
+# capacity/direction are unchanged.
+_CCOLS = CurveCols()
+
 if TYPE_CHECKING:
     from cellpy.readers.cellreader import CellpyCell
 
@@ -241,7 +249,10 @@ def get_cap(
 
     if insert_nan:
         _nan = externals.pandas.DataFrame(
-            {"capacity": [externals.numpy.nan], "voltage": [externals.numpy.nan]}
+            {
+                _CCOLS.capacity: [externals.numpy.nan],
+                _CCOLS.potential: [externals.numpy.nan],
+            }
         )
 
     converter_kwargs = dict()
@@ -391,8 +402,8 @@ def get_cap(
                     logging.debug("no first charge step found")
 
             if return_dataframe:
-                x_col = "voltage"
-                y_col = "capacity"
+                x_col = _CCOLS.potential
+                y_col = _CCOLS.capacity
                 if interpolate_along_cap:
                     x_col, y_col = y_col, x_col
 
@@ -401,8 +412,8 @@ def get_cap(
                     if not _first_step_c.empty:
                         _first_df = externals.pandas.DataFrame(
                             {
-                                "voltage": _first_step_v,
-                                "capacity": _first_step_c,
+                                _CCOLS.potential: _first_step_v,
+                                _CCOLS.capacity: _first_step_c,
                             }
                         )
                         if interpolated:
@@ -417,7 +428,7 @@ def get_cap(
                         if insert_nan:
                             _first_df = externals.pandas.concat([_first_df, _nan])
                         if categorical_column:
-                            _first_df["direction"] = -1
+                            _first_df[_CCOLS.direction] = -1
                     else:
                         _first_df = externals.pandas.DataFrame()
 
@@ -425,8 +436,8 @@ def get_cap(
                     if not _last_step_c.empty:
                         _last_df = externals.pandas.DataFrame(
                             {
-                                "voltage": _last_step_v.values,
-                                "capacity": _last_step_c.values,
+                                _CCOLS.potential: _last_step_v.values,
+                                _CCOLS.capacity: _last_step_c.values,
                             }
                         )
                         if interpolated:
@@ -441,7 +452,7 @@ def get_cap(
                         if insert_nan:
                             _last_df = externals.pandas.concat([_last_df, _nan])
                         if categorical_column:
-                            _last_df["direction"] = 1
+                            _last_df[_CCOLS.direction] = 1
                     else:
                         _last_df = externals.pandas.DataFrame()
 
@@ -457,9 +468,7 @@ def get_cap(
                 else:
                     c = externals.pandas.concat([_first_df, _last_df], axis=0)
                     if label_cycle_number:
-                        c.insert(0, "cycle", current_cycle)
-                        # c["cycle"] = current_cycle
-                        # c = c[["cycle", "voltage", "capacity", "direction"]]
+                        c.insert(0, _CCOLS.cycle_num, current_cycle)
                     if cycle_df.empty:
                         cycle_df = c
                     else:
@@ -467,8 +476,8 @@ def get_cap(
                 if capacity_then_voltage:
                     cols = cycle_df.columns.to_list()
                     new_cols = [
-                        cols.pop(cols.index("capacity")),
-                        cols.pop(cols.index("voltage")),
+                        cols.pop(cols.index(_CCOLS.capacity)),
+                        cols.pop(cols.index(_CCOLS.potential)),
                     ]
                     new_cols.extend(cols)
                     cycle_df = cycle_df[new_cols]

{cellpy-2.0.0a3 → cellpy-2.0.0a4}/cellpy/utils/collectors.py

@@ -19,7 +19,15 @@ import matplotlib.pyplot as plt
 import numpy as np
 
 import cellpy
+from cellpycore.config import CurveCols
+
 from cellpy.parameters.internal_settings import get_headers_journal
+
+# get_cap curve frames use native CurveCols names (#540): potential/cycle_num
+# replace the legacy voltage/cycle. The capacity-curve plotters below default
+# their x/y/z column selectors to these. (Summary and ICA collectors use their
+# own schemas and are left untouched.)
+_CCOLS = CurveCols()
 from cellpy.readers.data_structures import group_by_interpolate
 from cellpy.utils.batch import Batch
 from cellpy.utils.helpers import concat_summaries
@@ -1163,9 +1171,14 @@ class BatchSummaryCollector(BatchCollector):
         wide_cols = []
         value_cols = []
         sort_by = []
+        # summary collectors label the cycle column "cycle"; curve collectors
+        # carry the native CurveCols name "cycle_num" (#540).
         if "cycle" in cols:
             index = "cycle"
             cols.remove("cycle")
+        elif _CCOLS.cycle_num in cols:
+            index = _CCOLS.cycle_num
+            cols.remove(_CCOLS.cycle_num)
         else:
             print("Could not find index")
             return self.data
@@ -1965,9 +1978,9 @@ def spread_plot(curves, plotly_arguments=None, y_label_mapper=None, **kwargs):
 
 def sequence_plotter(
     collected_curves: pd.DataFrame,
-    x: str = "capacity",
-    y: str = "voltage",
-    z: str = "cycle",
+    x: str = _CCOLS.capacity,
+    y: str = _CCOLS.potential,
+    z: str = _CCOLS.cycle_num,
     g: str = "cell",
     standard_deviation: str = None,
     group: str = hdr_journal.group,
@@ -2359,10 +2372,10 @@ def sequence_plotter(
             seaborn_arguments["height"] = kwargs.pop("height", 3)
             seaborn_arguments["aspect"] = kwargs.pop("height", 1)
             sns.set_theme(style="darkgrid")
-            x = seaborn_arguments.get("x", "capacity")
-            y = seaborn_arguments.get("y", "voltage")
+            x = seaborn_arguments.get("x", _CCOLS.capacity)
+            y = seaborn_arguments.get("y", _CCOLS.potential)
             row = seaborn_arguments.get("row", hdr_journal.group)
-            hue = seaborn_arguments.get("hue", "cycle")
+            hue = seaborn_arguments.get("hue", _CCOLS.cycle_num)
             col = seaborn_arguments.get("col", hdr_journal.sub_group)
             height = seaborn_arguments.get("height", 3)
             aspect = seaborn_arguments.get("aspect", 1)
@@ -2520,9 +2533,9 @@ def sequence_plotter(
 def _cycles_plotter(
     collected_curves,
     cycles=None,
-    x="capacity",
-    y="voltage",
-    z="cycle",
+    x=_CCOLS.capacity,
+    y=_CCOLS.potential,
+    z=_CCOLS.cycle_num,
     g="cell",
     standard_deviation=None,
     default_title="Charge-Discharge Curves",
@@ -2579,7 +2592,7 @@ def _cycles_plotter(
         if cycles is not None:
             number_of_figs = len(cycles)
         else:
-            number_of_figs = len(collected_curves["cycle"].unique())
+            number_of_figs = len(collected_curves[_CCOLS.cycle_num].unique())
     elif method == "summary":
         number_of_figs = len(collected_curves["variable"].unique())
         sub_fig_min_height = 300
@@ -2889,9 +2902,9 @@ def cycles_plotter(
 
     return _cycles_plotter(
         collected_curves,
-        x="capacity",
-        y="voltage",
-        z="cycle",
+        x=_CCOLS.capacity,
+        y=_CCOLS.potential,
+        z=_CCOLS.cycle_num,
         g="cell",
         x_unit=x_unit,
         y_unit=y_unit,

{cellpy-2.0.0a3 → cellpy-2.0.0a4}/cellpy/utils/ica.py

@@ -13,9 +13,15 @@ from scipy.signal import savgol_filter
 from scipy.integrate import simpson
 from scipy.ndimage.filters import gaussian_filter1d
 
+from cellpycore.config import CurveCols
+
 from cellpy.exceptions import NullData
 from cellpy.readers.data_structures import collect_capacity_curves
 
+# get_cap curve frames use native CurveCols names (#540): potential, not voltage.
+# (ica's own dQ/dV output frame keeps its "voltage"/"dq" schema for now.)
+_CCOLS = CurveCols()
+
 
 # TODO: @jepe - documentation and tests
 # TODO: @jepe - fitting of o-c curves and differentiation
@@ -488,7 +494,7 @@ def dqdv_cycle(cycle_df, splitter=True, label_direction=False, **kwargs):
     # first
     try:
         converter = Converter(**kwargs)
-        converter.set_data(c_first["capacity"], c_first["voltage"])
+        converter.set_data(c_first[_CCOLS.capacity], c_first[_CCOLS.potential])
         converter.inspect_data()
         converter.pre_process_data()
         converter.increment_data()
@@ -516,7 +522,7 @@ def dqdv_cycle(cycle_df, splitter=True, label_direction=False, **kwargs):
     # last
     try:
         converter = Converter(**kwargs)
-        converter.set_data(c_last["capacity"], c_last["voltage"])
+        converter.set_data(c_last[_CCOLS.capacity], c_last[_CCOLS.potential])
         converter.inspect_data()
         converter.pre_process_data()
         converter.increment_data()
@@ -620,7 +626,8 @@ def dqdv_cycles(cycles_df, not_merged=False, label_direction=False, **kwargs):
         return pd.DataFrame()
 
     ica_dfs = list()
-    cycle_group = cycles_df.groupby("cycle")
+    # cycles_df is a get_cap curve frame — native CurveCols cycle key (#540).
+    cycle_group = cycles_df.groupby(_CCOLS.cycle_num)
     keys = list()
     for cycle_number, cycle in cycle_group:
         cycle = cycle.dropna()

{cellpy-2.0.0a3 → cellpy-2.0.0a4}/cellpy/utils/plotutils.py

@@ -19,6 +19,8 @@ import matplotlib.pyplot as plt
 import pandas as pd
 import numpy as np
 
+from cellpycore.config import CurveCols
+
 from cellpy.parameters.internal_settings import (
     get_headers_journal,
     get_headers_normal,
@@ -27,6 +29,10 @@ from cellpy.parameters.internal_settings import (
 )
 from cellpy.utils import helpers
 
+# get_cap curve frames use native CurveCols names (#540): potential/cycle_num
+# replace the legacy voltage/cycle (used by cycles_plot below).
+_CCOLS = CurveCols()
+
 plotly_available = importlib.util.find_spec("plotly") is not None
 seaborn_available = importlib.util.find_spec("seaborn") is not None
 
@@ -5782,14 +5788,14 @@ def cycles_plot(
     )
     df = c.get_cap(cycles=cycles, **kw_arguments)
     # Temporary fix to ensure that the cycles are plotted in the correct order:
-    df = df.sort_values(by=["cycle", "direction"])
+    df = df.sort_values(by=[_CCOLS.cycle_num, "direction"])
 
-    selector = df["cycle"] <= formation_cycles
+    selector = df[_CCOLS.cycle_num] <= formation_cycles
     form_cycles = df.loc[selector, :]
     rest_cycles = df.loc[~selector, :]
 
-    n_form_cycles = len(form_cycles["cycle"].unique())
-    n_rest_cycles = len(rest_cycles["cycle"].unique())
+    n_form_cycles = len(form_cycles[_CCOLS.cycle_num].unique())
+    n_rest_cycles = len(rest_cycles[_CCOLS.cycle_num].unique())
 
     capacity_unit = _get_capacity_unit(c, mode=mode)
 
@@ -5888,8 +5894,8 @@ def _cycles_plotter_matplotlib(
                 "Warning: try setting the figsize to (8, 4) or smaller for better visualization"
             )
         min_cycle, max_cycle = (
-            config.form_cycles["cycle"].min(),
-            config.form_cycles["cycle"].max(),
+            config.form_cycles[_CCOLS.cycle_num].min(),
+            config.form_cycles[_CCOLS.cycle_num].max(),
         )
         norm_formation = Normalize(vmin=min_cycle, vmax=max_cycle)
         cycle_sequence = np.arange(min_cycle, max_cycle + 1, 1)
@@ -5904,10 +5910,10 @@ def _cycles_plotter_matplotlib(
         s_m_formation = matplotlib.cm.ScalarMappable(
             cmap=c_m_formation, norm=norm_formation
         )
-        for name, group in config.form_cycles.groupby("cycle"):
+        for name, group in config.form_cycles.groupby(_CCOLS.cycle_num):
             ax.plot(
                 group["capacity"],
-                group["voltage"],
+                group[_CCOLS.potential],
                 lw=2,  # alpha=0.7,
                 color=s_m_formation.to_rgba(name),
                 label=f"Cycle {name}",
@@ -5916,8 +5922,8 @@ def _cycles_plotter_matplotlib(
             s_m_formation,
             ax=ax,  # label="Formation Cycle",
             ticks=np.arange(
-                config.form_cycles["cycle"].min(),
-                config.form_cycles["cycle"].max() + 1,
+                config.form_cycles[_CCOLS.cycle_num].min(),
+                config.form_cycles[_CCOLS.cycle_num].max() + 1,
                 1,
             ),
             shrink=shrink,
@@ -5932,22 +5938,22 @@ def _cycles_plotter_matplotlib(
         )
 
     norm = Normalize(
-        vmin=config.rest_cycles["cycle"].min(), vmax=config.rest_cycles["cycle"].max()
+        vmin=config.rest_cycles[_CCOLS.cycle_num].min(), vmax=config.rest_cycles[_CCOLS.cycle_num].max()
     )
     if config.cut_colorbar:
         cycle_sequence = np.arange(
-            config.rest_cycles["cycle"].min(), config.rest_cycles["cycle"].max() + 1, 1
+            config.rest_cycles[_CCOLS.cycle_num].min(), config.rest_cycles[_CCOLS.cycle_num].max() + 1, 1
         )
-        n = int(np.round(1.2 * config.rest_cycles["cycle"].max()))
+        n = int(np.round(1.2 * config.rest_cycles[_CCOLS.cycle_num].max()))
         c_m = ListedColormap(plt.get_cmap(config.colormap, n)(cycle_sequence))
     else:
         c_m = plt.get_cmap(config.colormap)
 
     s_m = matplotlib.cm.ScalarMappable(cmap=c_m, norm=norm)
-    for name, group in config.rest_cycles.groupby("cycle"):
+    for name, group in config.rest_cycles.groupby(_CCOLS.cycle_num):
         ax.plot(
             group["capacity"],
-            group["voltage"],
+            group[_CCOLS.potential],
             lw=1,
             color=s_m.to_rgba(name),
             label=f"Cycle {name}",
@@ -6000,9 +6006,9 @@ def _cycles_plotter_plotly(
         colormap = config.colormap
 
     if config.cut_colorbar:
-        range_color = [df["cycle"].min(), 1.2 * df["cycle"].max()]
+        range_color = [df[_CCOLS.cycle_num].min(), 1.2 * df[_CCOLS.cycle_num].max()]
     else:
-        range_color = [df["cycle"].min(), df["cycle"].max()]
+        range_color = [df[_CCOLS.cycle_num].min(), df[_CCOLS.cycle_num].max()]
     if (
         config.n_rest_cycles is not None
         and config.n_rest_cycles < plotly_max_individual_traces_for_lines
@@ -6021,12 +6027,12 @@ def _cycles_plotter_plotly(
         fig = px.line(
             config.rest_cycles,
             x="capacity",
-            y="voltage",
-            color="cycle",
+            y=_CCOLS.potential,
+            color=_CCOLS.cycle_num,
             title=config.fig_title,
             labels={
                 "capacity": f"Capacity ({config.capacity_unit})",
-                "voltage": f"Voltage ({c.cellpy_units.voltage})",
+                _CCOLS.potential: f"Voltage ({c.cellpy_units.voltage})",
             },
             color_discrete_sequence=cmap,
         )
@@ -6037,12 +6043,12 @@ def _cycles_plotter_plotly(
         fig = px.scatter(
             config.rest_cycles,
             x="capacity",
-            y="voltage",
+            y=_CCOLS.potential,
             title=config.fig_title,
-            color="cycle",
+            color=_CCOLS.cycle_num,
             labels={
                 "capacity": f"Capacity ({config.capacity_unit})",
-                "voltage": f"Voltage ({c.cellpy_units.voltage})",
+                _CCOLS.potential: f"Voltage ({c.cellpy_units.voltage})",
             },
             color_continuous_scale=colormap,
             range_color=range_color,
@@ -6051,11 +6057,11 @@ def _cycles_plotter_plotly(
         fig.update_traces(mode="lines+markers", line_color="white", line_width=1)
 
     if not config.form_cycles.empty and config.show_formation:
-        for name, group in config.form_cycles.groupby("cycle"):
+        for name, group in config.form_cycles.groupby(_CCOLS.cycle_num):
             logging.info(f"using go.Scatter for formation cycle(s) {name}")
             trace = go.Scatter(
                 x=group["capacity"],
-                y=group["voltage"],
+                y=group[_CCOLS.potential],
                 name=f"{name} (f.c.)",
                 hovertemplate=f"Formation Cycle {name}<br>Capacity: %{{x}}<br>Voltage: %{{y}}",
                 mode="lines",