Cell Measurement#

Client for managing cell measurements and time series data uploads.

Cell measurement client for managing time series test data.

This module provides the CellMeasurementClient for uploading, retrieving, and managing measurement data from battery cell testing. It supports efficient upload of large datasets using signed URLs and parquet format.

class ionworks.cell_measurement.CellMeasurementClient(client)[source]#

Bases: object

Client for managing cell measurement data.

Parameters:

client (Any)

UPLOAD_TIMEOUT: tuple[float, float] = (10, 300)#

Default timeout for signed URL uploads as (connect, read) in seconds.

__init__(client)[source]#

Initialize the CellMeasurementClient.

Parameters:

client (Any) – The HTTP client instance for making API calls.

Return type:

None

list(cell_instance_id)[source]#

List all cell measurements for a cell instance by instance ID.

Parameters:

cell_instance_id (str)

Return type:

list[CellMeasurement]

get(measurement_id)[source]#

Get a specific cell measurement by its ID only.

Parameters:

measurement_id (str)

Return type:

CellMeasurement

detail(measurement_id, use_signed_url=True, include_steps=True, include_cycles=True, include_time_series=True)[source]#

Fetch measurement data.

By default uses flat endpoints with parallel requests and downloads time series via signed URL. Set use_signed_url=False to use the legacy bundled /detail endpoint instead.

Use the include_* flags to skip fetching data you don’t need, which avoids unnecessary requests.

Parameters:

  • measurement_id (str) – The ID of the cell measurement.

  • use_signed_url (bool, optional) – If True (default), uses flat endpoints with parallel requests and signed-URL download. If False, uses the legacy /detail endpoint.

  • include_steps (bool, optional) – Whether to fetch step data. Defaults to True.

  • include_cycles (bool, optional) – Whether to fetch cycle metrics. Defaults to True.

  • include_time_series (bool, optional) – Whether to fetch time series data. Defaults to True.

Returns:

Measurement details with requested data fields. Fields not requested will be None.

Return type:

CellMeasurementDetail

steps(measurement_id)[source]#

Get step data for a measurement.

Parameters:

measurement_id (str) – The ID of the cell measurement.

Returns:

Step data (polars or pandas based on config).

Return type:

DataFrame

cycles(measurement_id)[source]#

Get cycle metrics for a measurement.

Parameters:

measurement_id (str) – The ID of the cell measurement.

Returns:

Cycle metrics (polars or pandas based on config).

Return type:

DataFrame

steps_and_cycles(measurement_id)[source]#

Get steps and cycles in one call.

More efficient than calling steps() and cycles() separately since cycles are derived from steps on the server.

Parameters:

measurement_id (str) – The ID of the cell measurement.

Returns:

Object with steps and cycles DataFrames.

Return type:

StepsAndCycles

time_series(measurement_id)[source]#

Download full time series via signed URL.

Downloads the raw parquet file directly from storage. Use this for full dataset access without backend processing.

Parameters:

measurement_id (str) – The ID of the cell measurement.

Returns:

Full time series data.

Return type:

DataFrame

update(measurement_id, data)[source]#

Update an existing cell measurement.

Parameters:

  • measurement_id (str) – The ID of the cell measurement to update.

  • data (dict[str, Any]) – Dictionary containing the fields to update.

Returns:

The updated cell measurement.

Return type:

CellMeasurement

delete(measurement_id)[source]#

Delete a cell measurement by measurement ID only.

Parameters:

measurement_id (str)

Return type:

None

create(cell_instance_id, measurement_detail, validate_strict=False)[source]#

Create a new cell measurement with steps and time series data.

Uses signed URL upload for better performance with large datasets. Data is uploaded directly to storage as parquet, bypassing backend JSON parsing. No database record is created until the upload is confirmed, preventing orphaned records if upload fails.

Parameters:

  • cell_instance_id (str) – The ID of the cell instance to create the measurement for.

  • measurement_detail (dict[str, Any]) –

    Dictionary containing ‘measurement’, ‘steps’, and ‘time_series’.

    • measurement: dict with ‘name’ (required) and ‘notes’

    • time_series: pandas DataFrame or dict with time series data

    • steps: optional dict with pre-calculated steps data

  • validate_strict (bool, optional) – If False (default), skips strict validation. If True, runs strict validation including minimum points per step.

Returns:

Response containing the created measurement, steps count, and file path.

Return type:

CellMeasurementBundleResponse

Raises:

MeasurementValidationError – If data validation fails. Validation checks include: - Positive current should correspond to discharge - Cumulative values should reset at each step

create_or_get(cell_instance_id, measurement_detail, validate_strict=False)[source]#

Create a new cell measurement or get existing.

Always returns a CellMeasurement regardless of whether the measurement was newly created or already existed.

Parameters:

  • cell_instance_id (str) – The ID of the cell instance.

  • measurement_detail (dict[str, Any]) – Dictionary containing measurement and time_series (same as create()).

  • validate_strict (bool, optional) – If False (default), skips strict validation. If True, runs strict validation including minimum points per step.

Returns:

The measurement (newly created or existing).

Return type:

CellMeasurement