Postprocess modiffications (#145)

* ignoring vscode settings

* changing name of schema from hold to rest

* Fixing nomenclature errors

Changing the ChargingState schema from 'hold' to 'rest' caused a number of
issues, which should now have been fixed.

* Changing the way we assign basic control methods

The way to assign the simpler control methods is more streamlined. Short rests
are tied only to their duration, independently of how many data points are
present. Other short steps are classified as either pulses if they have >=5 data
points, or short non-rests, in case there are <5 data points. Non-rest steps
that last longer than 30 seconds but have fewer than 5 datapoints are considered
unknown control method.

* style fix

* Allowing user to specify max duration of short period

When computing the control method, we now allow the user to specify what they
wish to consider is a short enough period to be classified as short rest, pulse,
or short non-rest. That value defaults to 30 seconds, as originally intended.

* Additional explanation to ControlMethod schema

Included additional explanation for some of the pre-specified control methods.

* StateOfCharge Enhancer considers coulombic efficiency

Now, the StateOfCharge RawDataEnhancer takes into account Coulombic Efficiency,
and outputs a third column to the raw dataframe, that of the CE adjusted charge,
meaning, the actual charge in the battery, rather than the one observed by the
cycler. It defaults to 1.0 (100% efficiency), so, by default, this new column
is equivalent to the `'cycled_charge'` column.

* style fix

* fixing demo notebook

Author: victorventuri

.gitignore

@@ -110,6 +110,9 @@ ENV/
 env.bak/
 venv.bak/
 
+# VSCode settings
+.vscode/
+
 # Spyder project settings
 .spyderproject
 .spyproject

battdat/io/arbin.py

@@ -49,7 +49,7 @@ def read_file(self, file: str, file_number: int = 0, start_cycle: int = 0,
         # TODO (wardlt): This function should move to post-processing
         def compute_state(x):
             if abs(x) < 1e-6:
-                return ChargingState.hold
+                return ChargingState.rest
             return ChargingState.charging if x > 0 else ChargingState.discharging
 
         df_out['state'] = df_out['current'].apply(compute_state)

battdat/io/maccor.py

@@ -96,7 +96,7 @@ def _parse_time(time: str) -> float:
             df_out['time'] = df['DPt Time'].apply(_parse_time)
 
         #   0 is rest, 1 is charge, -1 is discharge
-        df_out.loc[df_out['state'] == 'R', 'state'] = ChargingState.hold
+        df_out.loc[df_out['state'] == 'R', 'state'] = ChargingState.rest
         df_out.loc[df_out['state'] == 'C', 'state'] = ChargingState.charging
         df_out.loc[df_out['state'] == 'D', 'state'] = ChargingState.discharging
         df_out.loc[df_out['state'].apply(lambda x: x not in {'R', 'C', 'D'}), 'state'] = ChargingState.unknown

battdat/postprocess/integral.py

@@ -56,7 +56,7 @@ def __init__(self, reuse_integrals: bool = True):
         """
 
         Args:
-            reuse_integrals: Whether to reuse the ``cycle_capacity`` and ``cycle_energy`` if they are available
+            reuse_integrals: Whether to reuse the ``cycled_charge`` and ``cycled_energy`` if they are available
         """
         self.reuse_integrals = reuse_integrals
 
@@ -87,9 +87,9 @@ def _summarize(self, raw_data: pd.DataFrame, cycle_data: pd.DataFrame):
                 continue
 
             # Perform the integration
-            if self.reuse_integrals and 'cycle_energy' in cycle_subset.columns and 'cycle_capacity' in cycle_subset.columns:
-                capacity_change = cycle_subset['cycle_capacity'].values * 3600  # To A-s
-                energy_change = cycle_subset['cycle_energy'].values * 3600  # To J
+            if self.reuse_integrals and 'cycled_energy' in cycle_subset.columns and 'cycled_charge' in cycle_subset.columns:
+                capacity_change = cycle_subset['cycled_charge'].values * 3600  # To A-s
+                energy_change = cycle_subset['cycled_energy'].values * 3600  # To J
             else:
                 capacity_change = cumulative_trapezoid(cycle_subset['current'], x=cycle_subset['test_time'])
                 energy_change = cumulative_trapezoid(cycle_subset['current'] * cycle_subset['voltage'], x=cycle_subset['test_time'])
@@ -132,12 +132,45 @@ class StateOfCharge(RawDataEnhancer):
     The energy change is determined by integrating the product
     of current and voltage.
 
-    Output dataframe has 2 new columns:
-        - ``cycle_capacity``: Amount of charge charged since the beginning of the cycle, in A-hr
-        - ``cycle_energy``: Amount of energy charged since the beginning of the cycle, in J
+    Output dataframe has 3 new columns:
+        - ``cycled_charge``: Amount of observed charge cycled since the beginning of the cycle, in A-hr
+        - ``cycled_energy``: Amount of observed energy cycled since the beginning of the cycle, in W-hr
+        - ``CE_charge``: Amount of charge in the battery relative to the beginning of the cycle, accounting for Coulombic
+            Efficiency, in A-hr
     """
+    def __init__(self, coulombic_efficiency: float = 1.0):
+        """
+        Args:
+            coulombic_efficiency: Coulombic efficiency to use when computing the state of charge
+        """
+        self.coulombic_efficiency = coulombic_efficiency
 
-    column_names = ['cycle_capacity', 'cycle_energy']
+    @property
+    def coulombic_efficiency(self) -> float:
+        return self._ce
+
+    @coulombic_efficiency.setter
+    def coulombic_efficiency(self, value: float):
+        if value < 0 or value > 1:
+            raise ValueError('Coulombic efficiency must be between 0 and 1')
+        self._ce = value
+
+    @property
+    def column_names(self) -> List[str]:
+        return ['cycled_charge', 'cycled_energy', 'CE_charge']
+
+    def _get_CE_adjusted_curr(self, current: np.ndarray) -> np.ndarray:
+        """Adjust the current based on the coulombic efficiency
+
+        Args:
+            current: Current array in A
+
+        Returns:
+            Adjusted current array in A
+        """
+        adjusted_current = current.copy()
+        adjusted_current[current > 0] *= self.coulombic_efficiency
+        return adjusted_current
 
     def enhance(self, data: pd.DataFrame):
         # Add columns for the capacity and energy
@@ -153,9 +186,12 @@ def enhance(self, data: pd.DataFrame):
             cycle_subset = ordered_copy.iloc[start_ind:stop_ind]
 
             # Perform the integration
+            ce_adj_curr = self._get_CE_adjusted_curr(cycle_subset['current'].to_numpy())
             capacity_change = cumulative_trapezoid(cycle_subset['current'], x=cycle_subset['test_time'], initial=0)
+            ce_charge = cumulative_trapezoid(ce_adj_curr, x=cycle_subset['test_time'], initial=0)
             energy_change = cumulative_trapezoid(cycle_subset['current'] * cycle_subset['voltage'], x=cycle_subset['test_time'], initial=0)
 
             # Store them in the raw data
-            data.loc[cycle_subset['index'], 'cycle_capacity'] = capacity_change / 3600  # To A-hr
-            data.loc[cycle_subset['index'], 'cycle_energy'] = energy_change / 3600  # To W-hr
+            data.loc[cycle_subset['index'], 'cycled_charge'] = capacity_change / 3600  # To A-hr
+            data.loc[cycle_subset['index'], 'CE_charge'] = ce_charge / 3600  # To A-hr
+            data.loc[cycle_subset['index'], 'cycled_energy'] = energy_change / 3600  # To W-hr

battdat/postprocess/tagging.py

@@ -24,8 +24,16 @@ class AddMethod(RawDataEnhancer):
     of these points then assigning regions to constant voltage or current if one varied
     more than twice the other.
     """
+    def __init__(self, short_period_threshold: float = 30.0):
+        """
+        Args:
+            short_period_threshold: Maximum duration of a step to be considered a short step, in seconds
+        """
+        self.short_period_threshold = short_period_threshold
 
-    column_names = ['method']
+    @property
+    def column_names(self) -> List[str]:
+        return ['method']
 
     def enhance(self, df: pd.DataFrame):
         # Insert a new column into the dataframe, starting with everything marked as other
@@ -43,23 +51,26 @@ def enhance(self, df: pd.DataFrame):
             ind = cycle.index.values
             state = cycle['state'].values
 
-            if len(ind) < 5 and state[0] == ChargingState.hold:
-                # if there's a very short rest (less than 5 points)
-                # we label as "anomalous rest"
-                df.loc[ind, 'method'] = ControlMethod.short_rest
-            elif state[0] == ChargingState.hold:
-                # if there are 5 or more points it's a
-                # standard "rest"
+            if t[-1] - t[0] < self.short_period_threshold:
+                # The step is shorter than 30 seconds
+                if state[0] == ChargingState.rest:
+                    # If the step is a rest, we label it as a short rest
+                    df.loc[ind, 'method'] = ControlMethod.short_rest
+                elif len(ind) < 5:
+                    # The step contains fewer than 5 data points, so it is innapropriate to label it as anything
+                    # definitive other than a short non-rest
+                    df.loc[ind, 'method'] = ControlMethod.short_nonrest
+                else:
+                    # The step is a pulse
+                    df.loc[ind, 'method'] = ControlMethod.pulse
+            elif state[0] == ChargingState.rest:
+                # This is a standard rest, which lasts longer than 30 seconds
                 df.loc[ind, 'method'] = ControlMethod.rest
             elif len(ind) < 5:
-                # if it's a charge or discharge and there
-                # are fewer than 5 points it is an
-                # "anomalous charge or discharge"
-                df.loc[ind, 'method'] = ControlMethod.short_nonrest
-            elif t[-1] - t[0] < 30:
-                # if the step is less than 30 seconds
-                # index as "pulse"
-                df.loc[ind, 'method'] = ControlMethod.pulse
+                # The step spans over 30 seconds, but has fewer than 5 data points, rendering inadequate for control
+                # method determination
+                df.loc[ind, 'method'] = ControlMethod.unknown
+
             else:
                 # Normalize the voltage and current before determining which one moves "more"
                 for x in [voltage, current]:
@@ -191,7 +202,7 @@ def _determine_steps(df: DataFrame, column: str, output_col: str):
 def _determine_state(
         row: pd.Series,
         zero_threshold: float = 1.0e-4
-        ) -> Literal[ChargingState.charging, ChargingState.discharging, ChargingState.hold]:
+        ) -> Literal[ChargingState.charging, ChargingState.discharging, ChargingState.rest]:
     """
     Function to help determine the state of the cell based on the current
 
@@ -200,11 +211,11 @@ def _determine_state(
         zero_threshold: Maximum absolute value a current can take to be assigned rest. Defaults to 0.1 mA
 
     Returns
-        State of the cell, which can be either 'charging', 'discharging', or 'hold'
+        State of the cell, which can be either 'charging', 'discharging', or 'rest'
     """
     current = row['current']
     if abs(current) <= zero_threshold:
-        return ChargingState.hold
+        return ChargingState.rest
     elif current > 0.:
         return ChargingState.charging
     return ChargingState.discharging

battdat/schemas/column.py

@@ -11,7 +11,7 @@ class ChargingState(str, Enum):
     """Potential charging states of the battery"""
 
     charging = "charging"
-    hold = "hold"
+    rest = "resting"
     discharging = "discharging"
     unknown = "unknown"
 
@@ -20,19 +20,25 @@ class ControlMethod(str, Enum):
     """Method used to control battery during a certain step"""
 
     short_rest = "short_rest"
-    """A very short rest period. Defined as a step with 4 or fewer measurements with near-zero current"""
+    """A very short rest period.
+    Defined as a step with with near-zero current lasting for a short period of time, which defaults to 30 seconds."""
     rest = "rest"
     """An extended period of neither charging nor discharging"""
     short_nonrest = "short_nonrest"
-    """A very short period of charging or discharging. Defined as a step with 4 or fewer measurements with at least one non-zero current."""
+    """A very short period of charging or discharging.
+    Defined as a step with a non-zero current lasting for a short period of time (defaults to 30 seconds), but with
+    fewer than 5 data points."""
+    pulse = "pulse"
+    """A short period of a large current lasting for a short period of time, which defaults to 30 seconds.
+    Must contain at least 5 data points."""
     constant_current = "constant_current"
     """A step where the current is held constant"""
     constant_voltage = "constant_voltage"
     """A step where the voltage is held constant"""
     constant_power = "constant_power"
     """A step where the power is held constant"""
-    pulse = "pulse"
-    """A short period of a large current"""
+    unknown = "unknown"
+    """A step where the control method is not known"""
     other = "other"