Data Reading¶

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

Base Reader¶

class ionworks.data.read.BaseReader[source]¶

Bases: object

name: str = 'Unknown reader'¶

default_options: dict[str, Any] = {}¶

ALWAYS_NUMERIC_COLUMNS = ['Time [s]', 'Time [h]', 'Current [A]', 'Current [mA]', 'Current [mA.cm-2]', 'Voltage [V]', 'Temperature [degC]', 'Frequency [Hz]', 'Capacity [A.h]', 'Capacity [mA.h]', 'Energy [W.h]', 'Energy [mW.h]', 'Power [W]', 'Charge capacity [A.h]', 'Charge capacity [mA.h]', 'Discharge capacity [A.h]', 'Discharge capacity [mA.h]', 'Charge energy [W.h]', 'Charge energy [mW.h]', 'Discharge energy [W.h]', 'Discharge energy [mW.h]']¶

classmethod get_reader_types() → dict[str, type[BaseReader]][source]¶

classmethod get_reader_object(name: str) → BaseReader[source]¶

classmethod get_name() → str[source]¶

run(filename: str | Path, extra_column_mappings: dict[str, str] | None = None, options: dict[str, str] | None = None) → DataFrame[source]¶

standard_data_processing(data: DataFrame, columns_keep: list[str] | None = None) → DataFrame[source]¶

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:

data (pl.DataFrame) – The data to be processed.
columns_keep (list[str] | None, optional) – List of columns to keep from the data. Default is None.

Returns:

The processed data with standardized columns and formatting.

Return type:

pl.DataFrame

read_start_time(filename: str | Path, extra_column_mappings: dict[str, str] | None = None, options: dict[str, str] | None = None) → Any[source]¶

read_metadata(filename: str | Path, options: dict[str, str] | None = None) → dict[str, Any][source]¶

Read descriptive metadata that the file header carries, if any.

Grouped as the measurement API defines its fields, so the result needs no reshaping. This default reports the reader’s name plus whatever read_start_time() yields, so a caller can ask any reader without branching on type.

Returns:: test_setup["cycler"] – the reader’s name, which identifies the format, not the lab’s equipment, so a caller who knows the model ("Novonix UHPC") sets it themselves and merging keeps theirs. Plus start_time when the reader can determine one. Keys the file does not carry are omitted.
Return type:: dict[str, Any]

Functions¶

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

Parameters:

filename (str or Path) – The path to the cycler file to read.
reader (str | None, optional) – The name of the reader to use. See subclasses of iw.data.read.BaseReader. If not provided, the reader will be automatically detected from the file.
extra_column_mappings (dict, optional) – A dictionary of extra column mappings. The keys are the original column names and the values are the new column names.
extra_constant_columns (dict, 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.
options (dict, optional) – A dictionary of options to pass to the reader. See the specific reader’s documentation for available options.
save_dir (str or Path, optional) – The directory to save the time series data to. If not provided, the data will not be saved.

Returns:

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 - “Cycle discharge capacity [A.h]” : Discharge capacity accumulated per cycle - “Cycle charge capacity [A.h]” : Charge capacity accumulated per cycle - “Cycle discharge energy [W.h]” : Discharge energy accumulated per cycle - “Cycle charge energy [W.h]” : Charge energy accumulated per cycle - “Power [W]” : Power in watts (Voltage [V] * Current [A]) Additional columns may be present if specified in extra_column_mappings or extra_constant_columns.

Return type:

pl.DataFrame

ionworks.data.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, *, cell_spec: Any = None) → tuple[DataFrame, DataFrame][source]¶

Read a cycler file with time_series() and summarize its steps.

Validation mirrors the Ionworks API’s, so data that passes here passes on upload; options keys validate / validate_strict control it.

Parameters:

filename (str or Path) – The path to the cycler file to read.
reader (str | None, optional) – The name of the reader to use. See subclasses of iw.data.read.BaseReader. If not provided, the reader will be automatically detected from the file.
extra_column_mappings (dict, optional) – A dictionary of extra column mappings. The keys are the original column names and the values are the new column names.
extra_constant_columns (dict, optional) – A dictionary of extra constant columns. The keys are the column names and the values are the constant values to assign.
options (dict, 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_dir (str or Path, optional) – The directory to save the time series and steps data to. If not provided, the data will not be saved.
cell_spec (dict or object, optional) – The cell specification, used to type steps against its rated capacity. Preferred when known; see ionworks.data.steps.summarize().

Returns:

data (pl.DataFrame) – The processed time series data with standardized column names and units. See ionworks.data.read.time_series() for details.
steps (pl.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.

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

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

Parameters:

data (pl.DataFrame) – The time series dataframe.
extra_columns (list[str] | None, optional) – List of extra columns to keep. Default is None.

Returns:

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]” - “DC resistance [Ohm]” - “Step count” - “Cycle count” - “Frame” (only readers that recover calls write it) - “Discharge capacity [A.h]” - “Charge capacity [A.h]” - “Discharge energy [W.h]” - “Charge energy [W.h]” - “Power [W]” And any extra columns specified in extra_columns.

Return type:

pl.DataFrame

ionworks.data.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, keep_only_required_columns: bool = True, data_type: str | None = None) → dict[str, Any][source]¶

Read a cycler file into the time series, steps and measurement dict for upload.

The time series comes from ionworks.data.read.time_series_and_steps(), reduced to the required columns by ionworks.data.read.keep_required_columns(). The cycler name, test start time and any header metadata are added to the measurement dictionary.

Parameters:

filename (str | Path) – The path to the cycler file to read.
measurement (dict[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.
reader (str | None, optional) – The name of the reader to use. See subclasses of iw.data.read.BaseReader. If not provided, the reader will be automatically detected from the file.
extra_column_mappings (dict[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_columns (dict[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.
options (dict[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.
keep_only_required_columns (bool, optional) – If True, only the required columns are kept in the time series. Default is True. See ionworks.data.read.keep_required_columns() for the required columns.
data_type (str | 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:

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, with header metadata nested as the API defines it – see _merge_header_metadata().

Return type:

dict[str, Any]

ionworks.data.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[source]¶

Read the start time from the cycler file.

Parameters:

filename (str or Path) – The path to the cycler file to read.
reader (str | None, optional) – The name of the reader to use. See subclasses of iw.data.read.BaseReader. If not provided, the reader will be automatically detected from the file.
extra_column_mappings (dict[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.
options (dict[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:

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

Return type:

datetime