Move cycling metadata to subclass (#113)

README.md

@@ -5,14 +5,29 @@
 [![Coverage Status](https://coveralls.io/repos/github/ROVI-org/battery-data-toolkit/badge.svg?branch=main)](https://coveralls.io/github/ROVI-org/battery-data-toolkit?branch=main)
 [![PyPI version](https://badge.fury.io/py/battery-data-toolkit.svg)](https://badge.fury.io/py/battery-data-toolkit)
 
-The battery-data-toolkit, `batdata`, converts battery testing data from native formats to a standardized HDF5 file.
-These HDF5 files contain the metadata needed to understand the source of the data, 
-and can be easily manipulated by common analysis libraries (e.g., Pandas).
+The battery-data-toolkit, `battdat`, creates consistently-formatted collections of battery data.
+The library has three main purposes:
+
+1. *Storing battery data in standardized formats.* ``battdat`` stores data in 
+   [HDF5 or Parquet files](https://rovi-org.github.io/battery-data-toolkit/user-guide/formats.html) which include 
+   [extensive metadata](https://rovi-org.github.io/battery-data-toolkit/user-guide/schemas/index.html). 
+2. *Interfacing battery data with the PyData ecosystem*. The core data model,
+   [``BatteryDataset``](https://rovi-org.github.io/battery-data-toolkit/user-guide/dataset.html),
+   is built atop Pandas DataFrames.
+3. *Providing standard implementations of common analysis techniques*. ``battdat`` implements functions which
+   [ensure quality](https://rovi-org.github.io/battery-data-toolkit/user-guide/consistency/index.html)
+   or [perform common analyses](https://rovi-org.github.io/battery-data-toolkit/user-guide/post-processing/index.html).
 
 ## Installation
 
-The package can be installed with pip: `pip install battery-data-toolkit`
+Install ``battdat`` with pip: `pip install battery-data-toolkit`
 
 ## Documentation
 
-Please find the documentation at: https://rovi-org.github.io/battery-data-toolkit/
+Find the documentation at: https://rovi-org.github.io/battery-data-toolkit/
+
+## Support
+
+The motivation and funding for this project came from the Rapid Operational Validation Initiative (ROVI) sponsored by the Office of Electricity.
+The focus of ROVI is "to greatly reduce time required for emerging energy storage technologies to go from lab to market by developing new tools that will accelerate the testing and validation process needed to ensure commercial success." 
+If interested, you can read more about ROVI here.

battdat/consistency/current.py

@@ -50,7 +50,7 @@ def check_subset(self, time_series: pd.DataFrame) -> Optional[str]:
         most_stable_time = nonzero_current['test_time'].loc[most_stable_point]
         stable_window = nonzero_current.query(f'test_time < {most_stable_time} and test_time > {most_stable_time - self.window_length}')
         curr_volt_cov = np.cov(stable_window['voltage'], stable_window['test_time'])[0, 1]
-        if np.sign(curr_volt_cov) != np.sign(stable_window['current'].mean()):  # TODO (wardlt): Invert when we flip sign convention
+        if np.sign(curr_volt_cov) != np.sign(stable_window['current'].mean()):
             return (f'Potential sign error in current. Average current between test_time={most_stable_time - self.window_length:.1f}s and '
                     f'test_time={most_stable_time:.1f} is {stable_window["current"].mean():.1e} A and the covariance between the voltage and current '
                     f'is {curr_volt_cov:.1e} V-s. The current and this covariance should have the same sign.')

battdat/schemas/__init__.py

@@ -1,11 +1,11 @@
 """Schemas for battery data and metadata"""
-from datetime import date
 from typing import List, Tuple, Optional
 
 from pydantic import BaseModel, Field, AnyUrl
 
 from battdat.schemas.modeling import ModelMetadata
 from battdat.schemas.battery import BatteryDescription
+from battdat.schemas.cycling import CyclingProtocol
 from battdat.version import __version__
 
 
@@ -26,10 +26,7 @@ class BatteryMetadata(BaseModel, extra='allow'):
                                  iri="https://w3id.org/emmo#EMMO_463bcfda_867b_41d9_a967_211d4d437cfb")
 
     # Fields that describe the test protocol
-    cycler: Optional[str] = Field(None, description='Name of the cycling machine')
-    start_date: Optional[date] = Field(None, description="Date the initial test on the cell began")
-    set_temperature: Optional[float] = Field(None, description="Set temperature for the battery testing equipment. Units: C")
-    schedule: Optional[str] = Field(None, description="Schedule file used for the cycling machine")
+    test_protocol: Optional[CyclingProtocol] = Field(None, description="Method used to ")
 
     # Field that describe the battery assembly
     battery: Optional[BatteryDescription] = Field(None, description="Description of the battery being tested")

battdat/schemas/cycling.py

@@ -0,0 +1,13 @@
+"""Describing cycling protocol"""
+from datetime import date
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class CyclingProtocol(BaseModel, extra='allow'):
+    """Test protocol for cell cycling"""
+    cycler: Optional[str] = Field(None, description='Name of the cycling machine')
+    start_date: Optional[date] = Field(None, description="Date the initial test on the cell began")
+    set_temperature: Optional[float] = Field(None, description="Set temperature for the battery testing equipment. Units: C")
+    schedule: Optional[str] = Field(None, description="Schedule file used for the cycling machine")

docs/conf.py

@@ -6,7 +6,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'BattDat'
+project = 'Battery Data Toolkit'
 copyright = '2024'
 author = 'ROVI Team'
 
@@ -26,7 +26,7 @@
 html_static_path = ['_static']
 html_theme_options = {
     "logo": {
-        "text": "BatData",
+        "text": "BattData",
         "image_light": "_static/logo.png",
         "image_dark": "_static/logo.png",
     }

docs/index.rst

@@ -1,10 +1,20 @@
 Battery Data Toolkit
 ====================
 
-The battery-data-toolkit, ``battdat`` converts battery cycling data from native formats to a standardized HDF5 file.
-These HDF5 files contain the metadata needed to understand the source of the data,
-and can be easily manipulated by common analysis libraries (e.g., Pandas).
+The battery-data-toolkit, ``battdat``, creates consistently-formatted collections of battery data.
+The library has three main purposes:
 
+1. *Storing battery data in standardized formats.* ``battdat`` stores data in
+   `high-performance file formats <./user-guide/formats.html>`_ and include
+   `extensive metadata <./user-guide/schemas/index.html>`_ alongside data.
+2. *Interfacing battery data with the PyData ecosystem*. The core data model,
+   `BatteryDataset <./user-guide/dataset.html>`_,
+   is built atop Pandas DataFrames.
+3. *Providing standard implementations of common analysis techniques*. ``battdat`` implements functions which
+   `ensure quality <./user-guide/consistency/index.html>`_
+   or `perform common analyses <./user-guide/post-processing/index.html>`_.
+
+Source code: https://github.com/ROVI-org/battery-data-toolkit
 
 .. toctree::
    :maxdepth: 2

docs/source/consistency.rst

@@ -0,0 +1,24 @@
+Error Checking (``battdat.consistency``)
+========================================
+
+.. automodule:: battdat.consistency
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Base (``b.consistency.base``)
+-----------------------------
+
+.. automodule:: battdat.consistency.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Current (``b.consistency.current``)
+------------------------------------
+
+.. automodule:: battdat.consistency.current
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/schemas.rst

@@ -22,6 +22,15 @@ Metadata: Computation (``b.schemas.modeling``)
    :undoc-members:
    :show-inheritance:
 
+Metadata: Cycling Protocol (``b.schemas.cycling``)
+--------------------------------------------------
+
+.. automodule:: battdat.schemas.cycling
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
 Data: Time Series (``b.schemas.column``)
 ----------------------------------------
 

docs/user-guide/schemas/export-schemas.py

@@ -4,7 +4,7 @@
 from pydantic import BaseModel
 
 from battdat.schemas.column import RawData, CycleLevelData
-from battdat.schemas import BatteryMetadata, BatteryDescription, ModelMetadata
+from battdat.schemas import BatteryMetadata, BatteryDescription, ModelMetadata, CyclingProtocol
 from battdat.schemas.eis import EISData
 
 print('Exporting column schemas to RST...')
@@ -90,4 +90,8 @@ def expand_terms(metadata_cls: type[BaseModel], fo: TextIO, recurse: bool):
 
     expand_terms(ModelMetadata, fp, True)
 
+    print('Cycling Data', file=fp)
+    print('++++++++++++', file=fp)
+    print('Annotate how batteries were cycled following protocol description objects.\n', file=fp)
 
+    expand_terms(CyclingProtocol, fp, True)