Raw data

Raw data records let you archive the original files that came off your cycler — untouched — inside Ionworks Studio, then link them to the processed cell measurements they produced. This gives every measurement a clear provenance trail back to its source. Raw data records live under a project, not under a specific cell instance. One raw file can feed many measurements, and one measurement can be assembled from many raw files.

When to use raw data

Use raw data records when you want to:

Keep the untransformed cycler export (e.g. .mpr, .res, .nda, .txt, or a Neware / Maccor / Biologic file) alongside the processed time series it was converted into.
Trace a measurement back to the exact file — and file version — it came from.
Store one source file that was split into several measurements (for example, a single test file containing formation + RPT + cycling that you uploaded as three separate measurements).
Combine several source files into one measurement (for example, a run that was paused and resumed, producing two export files).

If you only care about the processed data, you do not need to create raw data records — regular measurement upload is enough. Raw data is additive provenance, not a replacement for preparing data and uploading data.

Raw data records store the file as-is. They are not processed into measurements automatically — you still convert your file with ionworksdata and upload the resulting measurement separately, then attach the raw file for provenance.

Upload a raw file

Upload any file from a local path or an open binary handle. The client derives the filename from the file path or handle:

raw = client.raw_data.upload(
    project_id=project.id,
    file="exports/cellA_formation.mpr",
    name="Cell A — formation export",
    metadata={"cycler": "Biologic VMP3", "operator": "Jane Smith"},
)

print(raw.id, raw.filename, raw.size_bytes)

Arguments:

Argument	Description
`project_id`	Project the raw file belongs to. Required.
`file`	Path (`str` or `os.PathLike`) or an open binary file-like object.
`name`	Human-readable label. Defaults to the file’s basename.
`metadata`	Free-form dict — cycler make/model, operator, channel, source path, etc.

The returned RawData object has id, project_id, name, filename, content_type, size_bytes, metadata, and timestamps.

List, get, and download

# List a project's raw files, newest first
files = client.raw_data.list(project_id=project.id, limit=50)

for r in files.items:
    print(r.id, r.name, r.filename, r.size_bytes)

# Fetch one record
raw = client.raw_data.get(raw_data_id)

# Get a short-lived signed download URL
url = client.raw_data.download_url(raw_data_id)

list returns a paginated response with items, count, and total. The download_url is signed and expires after a few minutes — request a fresh one each time you need to download the file.

Update and delete

name and metadata are patchable. The underlying file is immutable — to replace the bytes, delete the record and upload again.

client.raw_data.update(
    raw_data_id,
    name="Cell A — formation export (re-labeled)",
    metadata={"cycler": "Biologic VMP3", "channel": 4},
)

client.raw_data.delete(raw_data_id)

Deleting a raw data record removes the stored file and clears any links to measurements. The linked measurements themselves are not deleted.

Link raw files to measurements

The provenance link is many-to-many and lives on the measurement side of the SDK. Attaching is bulk and idempotent — re-attaching an already-linked file is a no-op.

# Attach one or more raw files to a measurement
client.cell_measurement.attach_raw_data(
    cell_measurement_id=measurement.id,
    raw_data_ids=[raw.id],
)

# List the raw files behind a measurement
sources = client.cell_measurement.list_raw_data(measurement.id)
for r in sources.items:
    print(r.filename)

# Detach one link (does not delete the raw file)
client.cell_measurement.detach_raw_data(
    cell_measurement_id=measurement.id,
    raw_data_id=raw.id,
)

To go the other direction — find every measurement that was produced from a given raw file — use list_measurements on the raw data client:

measurements = client.raw_data.list_measurements(raw_data_id)
for measurement_id in measurements.items:
    print(measurement_id)

Deleting a measurement removes only its provenance links, never the raw data record or its file. Raw files are independent, project-owned assets.

End-to-end example

Upload the processed measurement, then archive the original file and link them:

import ionworksdata as iwd

source_path = "exports/cellA_formation.mpr"

# 1. Process the cycler file into the Ionworks format
data = iwd.read(source_path)

# 2. Upload the processed measurement
bundle = client.cell_measurement.create(
    cell_instance.id,
    {
        "measurement": {"name": "Cell A — formation"},
        "time_series": data,
    },
    validate_strict=True,
)

# 3. Archive the original file
raw = client.raw_data.upload(
    project_id=project.id,
    file=source_path,
    name="Cell A — formation export",
    metadata={"cycler": "Biologic VMP3"},
)

# 4. Link the raw file to the measurement it produced
client.cell_measurement.attach_raw_data(
    cell_measurement_id=bundle.id,
    raw_data_ids=[raw.id],
)

Next steps

Preparing data

Convert cycler files into the Ionworks format before uploading a measurement.

Uploading data

Create cell specs, instances, and measurements via the Python API.

Measurements

Time series, properties, and file measurement types.

Projects

Group raw data, studies, and simulations by research initiative.

Get Started

Core Concepts

Data

Build

Pipelines

Simulate

Optimize

When to use raw data

Upload a raw file

List, get, and download

Update and delete

Link raw files to measurements

End-to-end example

Next steps

Preparing data

Uploading data

Measurements

Projects

​When to use raw data

​Upload a raw file

​List, get, and download

​Update and delete

​Link raw files to measurements

​End-to-end example

​Next steps

Preparing data

Uploading data

Measurements

Projects

When to use raw data

Upload a raw file

List, get, and download

Update and delete

Link raw files to measurements

End-to-end example

Next steps