Data Reading

Classes for reading data from various file formats. Currently the following cycler file formats are supported:

Base Reader

class ionworksdata.read.BaseReader

Bases: object

ALWAYS_NUMERIC_COLUMNS = ['Time [s]', 'Time [h]', 'Current [A]', 'Current [mA]', 'Current [mA.cm-2]', 'Voltage [V]', 'Temperature [degC]', 'Frequency [Hz]', 'Capacity [A.h]', 'Energy [W.h]', 'Charge capacity [A.h]', 'Discharge capacity [A.h]', 'Charge energy [W.h]', 'Discharge energy [W.h]']
default_options: dict[str, Any] = {}
classmethod get_name() → str
classmethod get_reader_object(name: str) → BaseReader
classmethod get_reader_types() → dict[str, type[BaseReader]]
name: str = 'Unknown reader'
read_start_time(filename: str | Path, extra_column_mappings: dict[str, str] | None = None, options: dict[str, str] | None = None) → Any
run(filename: str | Path, extra_column_mappings: dict[str, str] | None = None, options: dict[str, str] | None = None) → DataFrame
standard_data_processing(data: DataFrame, columns_keep: list[str] | None = None) → DataFrame

Standard data processing for all files. Skips NaNs in current and voltage, converts all numeric columns to float, resets “Time [s]” to start at zero, offsets duplicate time values, and only keeps the required columns.

Parameters

datapl.DataFrame

The data to be processed.

columns_keeplist[str] | None, optional

List of columns to keep from the data. Default is None.

Returns

pl.DataFrame

The processed data with standardized columns and formatting.

Functions

ionworksdata.read.time_series(filename: str | Path, reader: str | None = None, extra_column_mappings: dict[str, str] | None = None, extra_constant_columns: dict[str, float] | None = None, options: dict[str, str] | None = None, save_dir: str | Path | None = None) → DataFrame

Read the time series data from cycler file into a dataframe with standardized columns.

Parameters

filenamestr or Path

The path to the cycler file to read.

readerstr | None, optional

The name of the reader to use. See subclasses of iwdata.read.BaseReader. If not provided, the reader will be automatically detected from the file.

extra_column_mappingsdict, optional

A dictionary of extra column mappings. The keys are the original column names and the values are the new column names.

extra_constant_columnsdict, optional

A dictionary of extra constant columns. The keys are the column names and the values are the constant values to fill those columns with.

optionsdict, optional

A dictionary of options to pass to the reader. See the specific reader’s documentation for available options.

save_dirstr or Path, optional

The directory to save the time series data to. If not provided, the data will not be saved.

Returns

pl.DataFrame

The processed time series data with standardized columns: - “Time [s]” : Time in seconds - “Current [A]” : Current in amperes - “Voltage [V]” : Voltage in volts - “Temperature [degC]” : Temperature in degrees Celsius (optional) - “Step from cycler” : Step number from cycling data - “Cycle from cycler” : Cycle number from cycling data - “Frequency [Hz]” : Frequency in hertz (optional) - “Step count” : Cumulative step count - “Cycle count” : Cumulative cycle count (defaults to 0 if no cycle information is available) - “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 Additional columns may be present if specified in extra_column_mappings or extra_constant_columns.

ionworksdata.read.time_series_and_steps(filename: str | Path, reader: str | None = None, extra_column_mappings: dict[str, str] | None = None, extra_constant_columns: dict[str, float] | None = None, options: dict[str, Any] | None = None, save_dir: str | Path | None = None) → tuple[DataFrame, DataFrame]

Read the time series data from cycler file into a dataframe using ionworksdata.read.time_series() and then label the steps. The steps dataframe is created using ionworksdata.steps.summarize(). The steps output always includes a “Cycle count” column (defaults to 0 if no cycle information is available) and a “Cycle from cycler” column (only if provided in the input data).

When validation is enabled, runs the same validation as the Ionworks API so that data which passes here will pass API validation on upload. Control via the options dict: validate (default True) and validate_strict (default False).

Parameters

filenamestr or Path

The path to the cycler file to read.

readerstr | None, optional

The name of the reader to use. See subclasses of iwdata.read.BaseReader. If not provided, the reader will be automatically detected from the file.

extra_column_mappingsdict, optional

A dictionary of extra column mappings. The keys are the original column names and the values are the new column names.

extra_constant_columnsdict, optional

A dictionary of extra constant columns. The keys are the column names and the values are the constant values to assign.

optionsdict, optional

Options for the reader and for validation. Reader-specific keys are passed through to the reader. Additionally: - validate: bool, if True validate data before returning (default: True). - validate_strict: bool, if True use strict validation (default: False).

save_dirstr or Path, optional

The directory to save the time series and steps data to. If not provided, the data will not be saved.

Returns

datapl.DataFrame

The processed time series data with standardized column names and units. See ionworksdata.read.time_series() for details.

stepspl.DataFrame

The step summary data containing step types, cycle numbers, and other metadata.

Raises

MeasurementValidationError

If validation is enabled and the data fails API-matching validation.

ionworksdata.read.keep_required_columns(data: DataFrame, extra_columns: list[str] | None = None) → DataFrame

Returns a new dataframe with only required columns and any extra columns specified.

Parameters

datapl.DataFrame

The time series dataframe.

extra_columnslist[str] | None, optional

List of extra columns to keep. Default is None.

Returns

pl.DataFrame

A new dataframe containing only the required columns: - “Time [s]” - “Current [A]” - “Voltage [V]” - “Temperature [degC]” - “Frequency [Hz]” - “Z_Re [Ohm]” - “Z_Im [Ohm]” - “Z_Mod [Ohm]” - “Z_Phase [deg]” - “Step count” - “Cycle count” - “Discharge capacity [A.h]” - “Charge capacity [A.h]” - “Discharge energy [W.h]” - “Charge energy [W.h]” And any extra columns specified in extra_columns.

ionworksdata.read.measurement_details(filename: str | Path, measurement: dict[str, str], reader: str | None = None, extra_column_mappings: dict[str, str] | None = None, extra_constant_columns: dict[str, float] | None = None, options: dict[str, Any] | None = None, labels: list[dict[str, Any]] | None = None, keep_only_required_columns: bool = True, data_type: str | None = None) → dict[str, Any]

Read the time series data from cycler file into a dataframe using ionworksdata.read.time_series_and_steps() and then keep only the required columns in the time series using ionworksdata.read.keep_required_columns(). The cycler name and test start time are added to the measurement dictionary. Then return a dictionary with the time series data, the steps data, and the measurement dictionary.

Parameters

filenamestr | Path

The path to the cycler file to read.

measurementdict[str, str]

A dictionary containing the measurement information (e.g. protocol name, test name, etc.). This is updated inplace to include the cycler name and test start time.

readerstr | None, optional

The name of the reader to use. See subclasses of iwdata.read.BaseReader. If not provided, the reader will be automatically detected from the file.

extra_column_mappingsdict[str, str] | None, optional

A dictionary of extra column mappings. The keys are the original column names and the values are the new column names. Default is None.

extra_constant_columnsdict[str, float] | None, optional

A dictionary of extra constant columns. The keys are the column names and the values are the constant values. Default is None.

optionsdict[str, str] | None, optional

A dictionary of options to pass to the reader. See the reader’s documentation for the available options. Default is None.

labelslist[dict[str, Any]] | None, optional

A list of dictionaries containing the labels to add to the steps table. The keys are the label names and the values are the label options. If not provided, the default labels are added, which are cycling, pulse (charge and discharge), and EIS. If None, then the options dictionary must contain a “cell_metadata” key, which has a “Nominal cell capacity [A.h]” key, which is used to add the cycling and pulse labels. Default is None.

keep_only_required_columnsbool, optional

If True, only the required columns are kept in the time series. Default is True. See ionworksdata.read.keep_required_columns() for the required columns.

data_typestr | None, optional

The type of data in the file. Use "ocp" for open-circuit potential data, which uses a simplified processing path that only requires Voltage [V] (and optionally Capacity [A.h]). Default is None (standard cycler data).

Returns

dict[str, Any]

A dictionary containing: - “time_series”: pl.DataFrame with the time series data - “steps”: pl.DataFrame with the steps data - “measurement”: dict with the updated measurement information

ionworksdata.read.start_time(filename: str | Path, reader: str | None = None, extra_column_mappings: dict[str, str] | None = None, options: dict[str, str] | None = None) → Any

Read the start time from the cycler file.

Parameters

filenamestr or Path

The path to the cycler file to read.

readerstr | None, optional

The name of the reader to use. See subclasses of iwdata.read.BaseReader. If not provided, the reader will be automatically detected from the file.

extra_column_mappingsdict[str, str] | None, optional

Dictionary of additional column mappings to use when reading the file. The keys are the original column names and the values are the new column names. Default is None.

optionsdict[str, str] | None, optional

A dictionary of options to pass to the reader. See the reader’s documentation for the available options. Default is None.

Returns

datetime

The start time of the cycler file as a timezone-aware datetime object. Returns None if the reader cannot determine the start time.