> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 生データ

> 元のサイクラーファイルをそのまま保管し、そこから生成された測定に紐付けて完全なプロベナンスを保持します

生データレコードを使うと、**サイクラーから出力された元のファイル**を無加工のまま Ionworks Studio にアーカイブし、そこから生成された[セル測定](/ja/data/measurements)に紐付けることができます。これにより、すべての測定について元ファイルまで辿れる明確なプロベナンス（来歴）が得られます。

生データレコードは特定のセルインスタンスではなく、[プロジェクト](/ja/core-concepts/projects-studies)の下に保存されます。1 つの生ファイルを複数の測定のソースにすることも、1 つの測定を複数の生ファイルから組み立てることもできます。

## 生データを使う場面

以下のような場合に生データレコードを利用します:

* 未変換のサイクラー出力ファイル（例: `.mpr`、`.res`、`.nda`、`.txt`、Neware / Maccor / Biologic のファイル）を、そこから変換した処理済み[時系列](/ja/data/measurements#時系列)と一緒に保管しておきたい。
* 測定を、その元となった正確なファイル（およびファイルのバージョン）まで遡って追跡したい。
* 1 つのソースファイルを複数の測定に分割して保存した場合の記録を残したい（例: 形成 + RPT + サイクリングを含む単一のテストファイルを 3 つの別々の測定としてアップロードした場合）。
* 複数のソースファイルを 1 つの測定に統合する（例: 途中で一時停止して再開したためエクスポートファイルが 2 つに分かれたラン）。

処理済みデータのみを扱えばよい場合、生データレコードを作成する必要はありません。通常の測定アップロードで十分です。生データはあくまで追加のプロベナンスであり、[データの準備](/ja/data/preparing-data)や[データのアップロード](/ja/data/uploading)の置き換えではありません。

<Note>
  生データレコードはファイルを**そのまま**保管します。自動的に測定へ変換されることはありません。ファイルの変換は[`ionworksdata`](/ja/data/preparing-data) を使って引き続き行い、変換結果の測定を別途アップロードしたうえで、プロベナンスとして生ファイルを添付します。
</Note>

## 生ファイルをアップロード

ローカルパスまたはオープン済みのバイナリハンドルから任意のファイルをアップロードできます。クライアントはファイルパスまたはハンドルからファイル名を推定します:

```python theme={null}
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)
```

**引数:**

| 引数           | 説明                                                       |
| ------------ | -------------------------------------------------------- |
| `project_id` | 生ファイルが属するプロジェクト。必須。                                      |
| `file`       | パス (`str` または `os.PathLike`)、あるいはオープン済みのバイナリファイル様オブジェクト。 |
| `name`       | 人間向けのラベル。既定値はファイルのベース名。                                  |
| `metadata`   | 自由形式の辞書。サイクラーのメーカー・型番、オペレーター、チャネル、元パスなど。                 |

戻り値の `RawData` オブジェクトには `id`、`project_id`、`name`、`filename`、`content_type`、`size_bytes`、`metadata`、タイムスタンプが含まれます。

## リスト・取得・ダウンロード

```python theme={null}
# プロジェクトの生ファイルを新しい順に一覧
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)

# 1 件のレコードを取得
raw = client.raw_data.get(raw_data_id)

# 短時間有効な署名付きダウンロード URL を取得
url = client.raw_data.download_url(raw_data_id)
```

`list` は `items`、`count`、`total` を持つページネーション応答を返します。`download_url` は署名付きで数分後に失効するため、ファイルをダウンロードするたびに新しく取得してください。

## 更新と削除

`name` と `metadata` は部分更新できます。ファイル本体はイミュータブルです。バイト内容を差し替えるには、レコードを削除して再アップロードします。

```python theme={null}
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)
```

生データレコードを削除すると、保存されているファイルと、測定へのリンクがすべて削除されます。紐付いていた測定自体は削除されません。

## 生ファイルを測定に紐付ける

プロベナンスリンクは多対多で、SDK では測定側にメソッドがあります。添付はバルクかつ冪等で、すでに紐付いているファイルを再添付しても何も起きません。

```python theme={null}
# 1 つ以上の生ファイルを測定に添付
client.cell_measurement.attach_raw_data(
    cell_measurement_id=measurement.id,
    raw_data_ids=[raw.id],
)

# 測定の背後にある生ファイルを一覧
sources = client.cell_measurement.list_raw_data(measurement.id)
for r in sources.items:
    print(r.filename)

# 1 つのリンクを切り離す（生ファイル自体は削除されません）
client.cell_measurement.detach_raw_data(
    cell_measurement_id=measurement.id,
    raw_data_id=raw.id,
)
```

逆方向 — ある生ファイルから生成されたすべての測定を調べたい場合 — は、生データクライアント側の `list_measurements` を使います:

```python theme={null}
measurements = client.raw_data.list_measurements(raw_data_id)
for measurement_id in measurements.items:
    print(measurement_id)
```

<Note>
  測定を削除しても、プロベナンスリンクだけが取り除かれ、生データレコードやそのファイルは決して削除されません。生ファイルは独立した、プロジェクト所有のアセットです。
</Note>

## エンドツーエンドの例

処理済み測定をアップロードしたうえで、元ファイルをアーカイブし、両者を紐付けます:

```python theme={null}
import ionworksdata as iwd

source_path = "exports/cellA_formation.mpr"

# 1. サイクラーファイルを Ionworks フォーマットに変換
data = iwd.read(source_path)

# 2. 処理済み測定をアップロード
bundle = client.cell_measurement.create(
    cell_instance.id,
    {
        "measurement": {"name": "Cell A — formation"},
        "time_series": data,
    },
    validate_strict=True,
)

# 3. 元ファイルをアーカイブ
raw = client.raw_data.upload(
    project_id=project.id,
    file=source_path,
    name="Cell A — formation export",
    metadata={"cycler": "Biologic VMP3"},
)

# 4. 生ファイルを、それが生成した測定に紐付け
client.cell_measurement.attach_raw_data(
    cell_measurement_id=bundle.id,
    raw_data_ids=[raw.id],
)
```

## 次のステップ

<CardGroup cols={2}>
  <Card title="データの準備" icon="file-import" href="/ja/data/preparing-data">
    測定をアップロードする前に、サイクラーファイルを Ionworks フォーマットに変換します。
  </Card>

  <Card title="データのアップロード" icon="upload" href="/ja/data/uploading">
    Python API 経由でセル仕様、インスタンス、測定を作成します。
  </Card>

  <Card title="測定" icon="flask" href="/ja/data/measurements">
    時系列、プロパティ、ファイルの各測定タイプ。
  </Card>

  <Card title="プロジェクト" icon="cubes" href="/ja/core-concepts/projects-studies">
    生データ、スタディ、シミュレーションを研究テーマごとにグループ化します。
  </Card>
</CardGroup>