ionworksdata 0.4.0__tar.gz

ionworksdata-0.4.0/.gitignore

@@ -0,0 +1,30 @@
+private
+.idea
+*.egg-info
+__pycache__
+.vscode
+.DS_Store
+.venv
+build
+_version.py
+_build
+.coverage
+
+# Working directories for testing and development
+workspace
+configs
+output
+
+# Large test data files
+tests/test_data/repower2.csv
+
+# Figures
+*.png
+*.pdf
+*.jpg
+*.eps
+figures/
+
+# Local development/testing scripts
+.local/
+.mypy_cache/

ionworksdata-0.4.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ionworks Technologies Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ionworksdata-0.4.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: ionworksdata
+Version: 0.4.0
+Summary: Data processing for Ionworks software.
+License: MIT License
+        
+        Copyright (c) 2026 Ionworks Technologies Inc
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE.md
+Requires-Python: >=3.10
+Requires-Dist: fastexcel
+Requires-Dist: ionworks-api>=0.1.0
+Requires-Dist: iwutil>=0.3.10
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas<3.0.0
+Requires-Dist: polars-lts-cpu>=0.20.0
+Requires-Dist: pybamm
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: myst-nb; extra == 'dev'
+Requires-Dist: openpyxl; extra == 'dev'
+Requires-Dist: pydata-sphinx-theme; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: sphinx-design; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ionworks data
+
+Package to extract, transform, and validate battery data for use in Ionworks software.
+
+## Package overview
+
+`ionworksdata` is organized into the following modules:
+
+- Read: read raw data from files
+- Transform: transform time series data into Ionworks-compatible format
+- Label: label steps for easy processing or visualization
+
+## Data format
+
+The data is processed to be compatible with the Ionworks software. Documentation for the data format can be found in the [Knowledge base](https://www.notion.so/ionworks/Ionworks-Data-Data-management-tools-1ce7637d96ae801da6a1eb0e81669cac?pvs=4).
+
+# Data processing
+
+## Processing time series data
+
+Time series data can be extracted from a cycler file using the `read.time_series` function, which takes the filename and optionally the reader name (e.g. `csv`, `biologic_mpt`, `maccor`, `neware`, `repower`). If the reader is not specified, it will be automatically detected from the file. The function returns a Polars DataFrame.
+
+```python
+# With explicit reader
+data = iwdata.read.time_series("path/to/file.mpt", "biologic_mpt")
+
+# With auto-detection (reader is optional)
+data = iwdata.read.time_series("path/to/file.mpt")
+```
+
+The function automatically performs several processing steps and adds columns to the output:
+
+### Data Processing Steps
+
+1. **Reader-specific processing** (varies by reader):
+
+   - Column renaming to standardized names (e.g., "Voltage" → "Voltage [V]")
+   - Numeric coercion (removing thousands separators, converting strings to numbers)
+   - Dropping message/error rows (for some readers)
+   - Parsing timestamp columns and computing time if needed
+   - Converting time units (e.g., hours to seconds)
+   - Fixing unsigned current (if current is always positive, negate during charge)
+   - Validating and fixing decreasing times (if `time_offset_fix` option is set)
+
+2. **Standard data processing** (applied to all readers):
+
+   - Removing rows with null values in current or voltage columns
+   - Converting numeric columns to float64
+   - Resetting time to start at zero
+   - Offsetting duplicate timestamps by a small amount (1e-6 seconds) to preserve all data points
+   - Setting discharge current to be positive (charge current remains negative)
+
+3. **Post-processing**:
+   - Adding `Step count`: Cumulative step count (always present)
+   - Adding `Discharge capacity [A.h]`: Discharge capacity in ampere-hours (always present)
+   - Adding `Charge capacity [A.h]`: Charge capacity in ampere-hours (always present)
+   - Adding `Discharge energy [W.h]`: Discharge energy in watt-hours (always present)
+   - Adding `Charge energy [W.h]`: Charge energy in watt-hours (always present)
+
+### Output Columns
+
+The output always includes:
+
+- `Time [s]`: Time in seconds
+- `Current [A]`: Current in amperes
+- `Voltage [V]`: Voltage in volts
+- `Step count`: Cumulative step count
+- `Discharge capacity [A.h]`: Discharge capacity in ampere-hours
+- `Charge capacity [A.h]`: Charge capacity in ampere-hours
+- `Discharge energy [W.h]`: Discharge energy in watt-hours
+- `Charge energy [W.h]`: Charge energy in watt-hours
+
+Optional columns (if present in source data):
+
+- `Step from cycler`: Step number from cycler file
+- `Cycle from cycler`: Cycle number from cycler file
+- `Temperature [degC]`: Temperature in degrees Celsius
+- `Frequency [Hz]`: Frequency in hertz
+
+For information on the expected and returned columns, see the reader documentation. Additional columns can be added by passing a dictionary to the `extra_column_mappings` argument.
+
+```python
+data = iwdata.read.time_series(
+    "path/to/file.mpt", "biologic_mpt", extra_column_mappings={"My new column": "Old column name"}
+)
+```
+
+## Processing step data
+
+Given a processed time series data, the step summary data can be extracted as follows:
+
+```python
+steps = iwdata.label.Steps.get_step_types_for(data)
+```
+
+This function identifies distinct steps within battery cycling data by detecting changes in the "Step count" column (which must be present in the input data). For each identified step, it extracts and calculates relevant metrics (voltage, current, capacity, energy, etc.) and determines the step type.
+
+The output always includes:
+
+- `Cycle count`: Cumulative cycle count (defaults to 0 if no cycle information is available)
+- `Cycle from cycler`: Cycle number from cycler file (only if provided in the input data)
+- `Discharge capacity [A.h]`: Discharge capacity for the step
+- `Charge capacity [A.h]`: Charge capacity for the step
+- `Discharge energy [W.h]`: Discharge energy for the step
+- `Charge energy [W.h]`: Charge energy for the step
+- `Step from cycler`: Step number from cycler file (only if provided in the input data)
+
+**Note:** The `step_column` and `cycle_column` parameters have been removed. The function now always uses "Step count" for step identification and "Cycle from cycler" (if available) for cycle tracking.
+
+Alternatively, the time series and step data can be extracted together using the `read.time_series_and_steps` function.
+
+```python
+# With explicit reader
+data, steps = iwdata.read.time_series_and_steps("path/to/file.mpt", "biologic_mpt")
+
+# With auto-detection (reader is optional)
+data, steps = iwdata.read.time_series_and_steps("path/to/file.mpt")
+```
+
+## Labeling steps
+
+Steps can be labeled using the classes in the `label` module. For example, the following code labels the steps as cycling and pulse (charge and discharge).
+
+```python
+options = {"cell_metadata": {"Nominal cell capacity [A.h]": 5}}
+steps = iwdata.label.Cycling.steps(steps, options=options)
+for direction in ["charge", "discharge"]:
+    options["current direction"] = direction
+    steps = iwdata.label.Pulse.steps(steps, options=options)
+```
+
+## Measurement details
+
+The function `ionworksdata.read.measurement_details` can be used to return a `measurement_details` dictionary, which has keys "measurement", "time_series", and "steps". You need to first create the measurement dictionary (which contains details about the test, such as its name), and then pass it to the function along with the reader name and filename, and any additional arguments. The function will return the updated measurement details dictionary, which includes information extracted from the file, such as the start time, and the cycler name. This function also automatically labels the steps with some sensible defaults (custom labels can be added by passing a list of dictionaries to the `labels` argument).
+
+```python3
+measurement_details = iwdata.read.measurement_details(
+    "path/to/file.mpt",
+    measurement,
+    "biologic_mpt",
+    options={"cell_metadata": {"Nominal cell capacity [A.h]": 5}},
+)
+measurement = measurement_details["measurement"]
+time_series = measurement_details["time_series"]
+steps = measurement_details["steps"]
+```

ionworksdata-0.4.0/README.md

@@ -0,0 +1,146 @@
+# Ionworks data
+
+Package to extract, transform, and validate battery data for use in Ionworks software.
+
+## Package overview
+
+`ionworksdata` is organized into the following modules:
+
+- Read: read raw data from files
+- Transform: transform time series data into Ionworks-compatible format
+- Label: label steps for easy processing or visualization
+
+## Data format
+
+The data is processed to be compatible with the Ionworks software. Documentation for the data format can be found in the [Knowledge base](https://www.notion.so/ionworks/Ionworks-Data-Data-management-tools-1ce7637d96ae801da6a1eb0e81669cac?pvs=4).
+
+# Data processing
+
+## Processing time series data
+
+Time series data can be extracted from a cycler file using the `read.time_series` function, which takes the filename and optionally the reader name (e.g. `csv`, `biologic_mpt`, `maccor`, `neware`, `repower`). If the reader is not specified, it will be automatically detected from the file. The function returns a Polars DataFrame.
+
+```python
+# With explicit reader
+data = iwdata.read.time_series("path/to/file.mpt", "biologic_mpt")
+
+# With auto-detection (reader is optional)
+data = iwdata.read.time_series("path/to/file.mpt")
+```
+
+The function automatically performs several processing steps and adds columns to the output:
+
+### Data Processing Steps
+
+1. **Reader-specific processing** (varies by reader):
+
+   - Column renaming to standardized names (e.g., "Voltage" → "Voltage [V]")
+   - Numeric coercion (removing thousands separators, converting strings to numbers)
+   - Dropping message/error rows (for some readers)
+   - Parsing timestamp columns and computing time if needed
+   - Converting time units (e.g., hours to seconds)
+   - Fixing unsigned current (if current is always positive, negate during charge)
+   - Validating and fixing decreasing times (if `time_offset_fix` option is set)
+
+2. **Standard data processing** (applied to all readers):
+
+   - Removing rows with null values in current or voltage columns
+   - Converting numeric columns to float64
+   - Resetting time to start at zero
+   - Offsetting duplicate timestamps by a small amount (1e-6 seconds) to preserve all data points
+   - Setting discharge current to be positive (charge current remains negative)
+
+3. **Post-processing**:
+   - Adding `Step count`: Cumulative step count (always present)
+   - Adding `Discharge capacity [A.h]`: Discharge capacity in ampere-hours (always present)
+   - Adding `Charge capacity [A.h]`: Charge capacity in ampere-hours (always present)
+   - Adding `Discharge energy [W.h]`: Discharge energy in watt-hours (always present)
+   - Adding `Charge energy [W.h]`: Charge energy in watt-hours (always present)
+
+### Output Columns
+
+The output always includes:
+
+- `Time [s]`: Time in seconds
+- `Current [A]`: Current in amperes
+- `Voltage [V]`: Voltage in volts
+- `Step count`: Cumulative step count
+- `Discharge capacity [A.h]`: Discharge capacity in ampere-hours
+- `Charge capacity [A.h]`: Charge capacity in ampere-hours
+- `Discharge energy [W.h]`: Discharge energy in watt-hours
+- `Charge energy [W.h]`: Charge energy in watt-hours
+
+Optional columns (if present in source data):
+
+- `Step from cycler`: Step number from cycler file
+- `Cycle from cycler`: Cycle number from cycler file
+- `Temperature [degC]`: Temperature in degrees Celsius
+- `Frequency [Hz]`: Frequency in hertz
+
+For information on the expected and returned columns, see the reader documentation. Additional columns can be added by passing a dictionary to the `extra_column_mappings` argument.
+
+```python
+data = iwdata.read.time_series(
+    "path/to/file.mpt", "biologic_mpt", extra_column_mappings={"My new column": "Old column name"}
+)
+```
+
+## Processing step data
+
+Given a processed time series data, the step summary data can be extracted as follows:
+
+```python
+steps = iwdata.label.Steps.get_step_types_for(data)
+```
+
+This function identifies distinct steps within battery cycling data by detecting changes in the "Step count" column (which must be present in the input data). For each identified step, it extracts and calculates relevant metrics (voltage, current, capacity, energy, etc.) and determines the step type.
+
+The output always includes:
+
+- `Cycle count`: Cumulative cycle count (defaults to 0 if no cycle information is available)
+- `Cycle from cycler`: Cycle number from cycler file (only if provided in the input data)
+- `Discharge capacity [A.h]`: Discharge capacity for the step
+- `Charge capacity [A.h]`: Charge capacity for the step
+- `Discharge energy [W.h]`: Discharge energy for the step
+- `Charge energy [W.h]`: Charge energy for the step
+- `Step from cycler`: Step number from cycler file (only if provided in the input data)
+
+**Note:** The `step_column` and `cycle_column` parameters have been removed. The function now always uses "Step count" for step identification and "Cycle from cycler" (if available) for cycle tracking.
+
+Alternatively, the time series and step data can be extracted together using the `read.time_series_and_steps` function.
+
+```python
+# With explicit reader
+data, steps = iwdata.read.time_series_and_steps("path/to/file.mpt", "biologic_mpt")
+
+# With auto-detection (reader is optional)
+data, steps = iwdata.read.time_series_and_steps("path/to/file.mpt")
+```
+
+## Labeling steps
+
+Steps can be labeled using the classes in the `label` module. For example, the following code labels the steps as cycling and pulse (charge and discharge).
+
+```python
+options = {"cell_metadata": {"Nominal cell capacity [A.h]": 5}}
+steps = iwdata.label.Cycling.steps(steps, options=options)
+for direction in ["charge", "discharge"]:
+    options["current direction"] = direction
+    steps = iwdata.label.Pulse.steps(steps, options=options)
+```
+
+## Measurement details
+
+The function `ionworksdata.read.measurement_details` can be used to return a `measurement_details` dictionary, which has keys "measurement", "time_series", and "steps". You need to first create the measurement dictionary (which contains details about the test, such as its name), and then pass it to the function along with the reader name and filename, and any additional arguments. The function will return the updated measurement details dictionary, which includes information extracted from the file, such as the start time, and the cycler name. This function also automatically labels the steps with some sensible defaults (custom labels can be added by passing a list of dictionaries to the `labels` argument).
+
+```python3
+measurement_details = iwdata.read.measurement_details(
+    "path/to/file.mpt",
+    measurement,
+    "biologic_mpt",
+    options={"cell_metadata": {"Nominal cell capacity [A.h]": 5}},
+)
+measurement = measurement_details["measurement"]
+time_series = measurement_details["time_series"]
+steps = measurement_details["steps"]
+```

ionworksdata-0.4.0/ionworksdata/__init__.py

@@ -0,0 +1,11 @@
+from . import steps, transform, util, read, cycle_metrics
+from .load import DataLoader, OCPDataLoader
+from .piecewise_linear_timeseries import PiecewiseLinearTimeseries
+from .logger import logger, set_logging_level, get_new_logger
+from .settings import get_settings, update_settings, reset_settings
+
+try:
+    from ionworksdata._version import __version__
+except ModuleNotFoundError:
+    # Fallback for when the library is a submodule
+    __version__ = "0.0.0"

ionworksdata-0.4.0/ionworksdata/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
+
+__commit_id__ = commit_id = None