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

> W&B 表を作成してデータを追加し、ログすることで、実験の run から得られた構造化データを可視化およびクエリできます。

# 表をログする

`wandb.Table` を使用してデータをログすると、W\&B でデータを可視化およびクエリできます。このガイドでは、次の方法について説明します。

1. [表を作成する](/ja/products/wandb/track/log/log-tables#create-tables)
2. [データを追加する](/ja/products/wandb/track/log/log-tables#add-data)
3. [データを取得する](/ja/products/wandb/track/log/log-tables#retrieve-data)
4. [表を保存する](/ja/products/wandb/track/log/log-tables#save-tables)

<h2 id="create-tables">
  表を作成する
</h2>

表を定義するには、データの各行に表示したい列を指定します。各行には、トレーニングデータセット内の 1 つの項目、トレーニング中の特定のステップやエポック、テスト項目に対するモデルの予測、モデルが生成したオブジェクトなどが該当します。各列には、数値、テキスト、ブール値、画像、動画、オーディオなどの固定のタイプがあります。タイプを事前に指定する必要はありません。各列に名前を付け、その列インデックスにはそのタイプのデータのみを渡すようにしてください。より詳しい例については、[W\&B 表ガイド](https://forge.coreweave.com/wandb/stacey/mnist-viz/reports/Guide-to-W-B-Tables--Vmlldzo2NTAzOTk#1.-how-to-log-a-wandb.table)を参照してください。

`wandb.Table` コンストラクターは、次の 2 つのいずれかの方法で使用します。

1. **行のリスト:**

   名前付きの列とデータ行をログします。たとえば、次のコードスニペットは 2 行 3 列の表を生成します。

   ```python theme={"system"}
   wandb.Table(columns=["a", "b", "c"], data=[["1a", "1b", "1c"], ["2a", "2b", "2c"]])
   ```

2. **Pandas データフレーム:** `wandb.Table(dataframe=my_df)` を使用してデータフレームをログします。列名はデータフレームから抽出されます。

<h4 id="from-an-existing-array-or-dataframe">
  既存の配列またはデータフレームから作成する
</h4>

```python theme={"system"}
# モデルが 4 枚の画像に対する予測を返し、
# 次のフィールドが得られているとします:
# - 画像 ID
# - wandb.Image() でラップした画像のピクセル
# - モデルが予測したラベル
# - 正解ラベル
my_data = [
    [0, wandb.Image("img_0.jpg"), 0, 0],
    [1, wandb.Image("img_1.jpg"), 8, 0],
    [2, wandb.Image("img_2.jpg"), 7, 1],
    [3, wandb.Image("img_3.jpg"), 1, 1],
]

# 対応する列を指定して wandb.Table() を作成します
columns = ["id", "image", "prediction", "truth"]
test_table = wandb.Table(data=my_data, columns=columns)
```

<h2 id="add-data">
  データを追加する
</h2>

表はミュータブルです。スクリプトの実行中に、最大 200,000 行まで表にデータを追加できます。表にデータを追加する方法は 2 つあります。

1. **行を追加する**: `table.add_data("3a", "3b", "3c")`。新しい行はリストとして渡さない点に注意してください。行がリスト形式の場合は、スター記法 `*` を使用してリストを位置引数に展開します (例: `table.add_data(*my_row_list)`) 。行のエントリ数は、表の列数と一致している必要があります。
2. **列を追加する**: `table.add_column(name="col_name", data=col_data)`。`col_data` の長さは、表の現在の行数と一致している必要があります。`col_data` には、リストデータまたは NumPy NDArray を指定できます。

<h3 id="adding-data-incrementally">
  データを段階的に追加する
</h3>

このコードサンプルでは、W\&B の表を作成し、データを段階的に追加していく方法を示します。考えられるすべてのラベルの信頼度スコアを含む列をあらかじめ定義して表を作成し、推論中にデータを 1 行ずつ追加します。また、[run を再開する際に表へデータを段階的に追加する](#adding-data-to-resumed-runs)こともできます。

```python theme={"system"}
# 各ラベルの信頼度スコアを含め、表の列を定義します
columns = ["id", "image", "guess", "truth"]
for digit in range(10):  # 各数字 (0～9) の信頼度スコア列を追加します
    columns.append(f"score_{digit}")

# 定義した列で表を初期化します
test_table = wandb.Table(columns=columns)

# テストデータセットを順に処理し、表に 1 行ずつデータを追加します
# 各行には、画像 ID、画像、予測ラベル、正解ラベル、信頼度スコアが含まれます
for img_id, img in enumerate(mnist_test_data):
    true_label = mnist_test_data_labels[img_id]  # 正解ラベル
    guess_label = my_model.predict(img)  # 予測ラベル
    test_table.add_data(
        img_id, wandb.Image(img), guess_label, true_label
    )  # 表に行データを追加します
```

<h4 id="adding-data-to-resumed-runs">
  再開した run へのデータの追加
</h4>

再開した run では、アーティファクトから既存の表を読み込み、データの最終行を取得して、更新したメトリクスを追加することで、W\&B の表を段階的に更新できます。その後、互換性を確保するために表を再初期化し、更新したバージョンを W\&B にログします。

```python theme={"system"}
import wandb

# run を初期化します 
with wandb.init(project="my_project") as run:

    # アーティファクトから既存の表を読み込みます
    best_checkpt_table = run.use_artifact(table_tag).get(table_name)

    # 再開に備えて、表からデータの最終行を取得します
    best_iter, best_metric_max, best_metric_min = best_checkpt_table.data[-1]

    # 必要に応じて最良のメトリクスを更新します

    # 更新したデータを表に追加します
    best_checkpt_table.add_data(best_iter, best_metric_max, best_metric_min)

    # 互換性を確保するため、更新後のデータで表を再初期化します
    best_checkpt_table = wandb.Table(
        columns=["col1", "col2", "col3"], data=best_checkpt_table.data
    )

    # run を初期化します
    with wandb.init() as run:

        # 更新した表を W&B にログします
        run.log({table_name: best_checkpt_table})
```

<h2 id="retrieve-data">
  データを取得する
</h2>

表 に格納したデータには、列単位または行単位でアクセスできます。

1. **行イテレーター**: `for ndx, row in table.iterrows(): ...` のように 表 の行イテレーターを使用すると、データの行を効率的に反復処理できます。
2. **列を取得する**: `table.get_column("col_name")` を使用して、データの列を取得します。また、`convert_to="numpy"` を渡すと、列をプリミティブ値の NumPy NDArray に簡単に変換できます。列に `wandb.Image` などのメディアタイプが含まれている場合は、この方法で基になるデータに直接アクセスできます。

<h2 id="save-tables">
  表を保存する
</h2>

スクリプトでデータの表 (モデルの予測結果の表など) を生成したら、W\&B に保存すると結果をリアルタイムで可視化できます。

<h3 id="log-a-table-to-a-run">
  表を run にログする
</h3>

次のように `wandb.Run.log()` を使用して、表を run に保存します。

```python theme={"system"}
with wandb.init() as run:
    my_table = wandb.Table(columns=["a", "b"], data=[["1a", "1b"], ["2a", "2b"]])
    run.log({"table_key": my_table})
```

同じキーに表をログするたびに、その表の新しいバージョンが作成され、バックエンドに保存されます。そのため、同じキーにログしている限り、複数のトレーニングステップにわたって同じ表をログし、モデルの予測が時間とともにどう改善していくかを確認したり、異なる run 間で表を比較したりできます。ログできる行数は最大 200,000 行です。

<Note>
  200,000 行を超えてログするには、次のように制限を上書きできます。

  `wandb.Table.MAX_ARTIFACT_ROWS = X`

  ただし、UI でクエリが遅くなるなど、パフォーマンスの問題が発生する可能性が高くなります。
</Note>

<h3 id="access-tables-programmatically">
  プログラムから表にアクセスする
</h3>

バックエンドでは、表 はアーティファクトとして保存されます。特定のバージョンにアクセスするには、アーティファクト API を使用します。

```python theme={"system"}
with wandb.init() as run:
    my_table = run.use_artifact("run-<run-id>-<table-name>:<tag>").get("<table-name>")
```

アーティファクト の詳細については、Developer Guide の [アーティファクト の章](/ja/products/wandb/artifacts)を参照してください。

<h3 id="visualize-tables">
  表を可視化する
</h3>

この方法でログした表は、Workspace の Run page と Project page の両方に表示されます。詳細については、[表を可視化して分析する](/ja/products/wandb/tables/visualize-tables)を参照してください。

<h2 id="artifact-tables">
  アーティファクトの表
</h2>

`artifact.add()` を使用すると、表を Workspace ではなく run の アーティファクト セクションにログできます。これは、一度だけログして以降の run で参照したいデータセットがある場合に便利です。

```python theme={"system"}
with wandb.init(project="my_project") as run:
    # 意味のある区切りのステップごとに wandb Artifact を作成します
    test_predictions = wandb.Artifact("mnist_test_preds", type="predictions")

    # [前述の手順で予測データを作成します]
    test_table = wandb.Table(data=data, columns=columns)
    test_predictions.add(test_table, "my_test_key")
    run.log_artifact(test_predictions)
```

[画像データを使用した artifact.add() の詳細な例](https://wandb.me/dsviz-nature-colab)についてはこちらの Colab を、アーティファクト と 表 を使用して[表形式データのバージョン管理と重複排除を行う](https://wandb.me/TBV-Dedup)例についてはこちらの Report を参照してください。

<h3 id="join-artifact-tables">
  アーティファクトの表を結合する
</h3>

ローカルで作成した表や、他のアーティファクトから取得した表は、`wandb.JoinedTable(table_1, table_2, join_key)` を使用して結合できます。

| 引数 | 説明 |
| - | - |
| table\_1 | (str, `wandb.Table`, ArtifactEntry) アーティファクト内の `wandb.Table` へのパス、表オブジェクト、または ArtifactEntry |
| table\_2 | (str, `wandb.Table`, ArtifactEntry) アーティファクト内の `wandb.Table` へのパス、表オブジェクト、または ArtifactEntry |
| join\_key | (str, \[str, str]) 結合に使用するキー (1 つまたは複数) |

アーティファクトのコンテキストで以前にログした 2 つの表を結合するには、それらをアーティファクトから取得し、結合した結果を新しい表にします。

たとえば次のコード例では、元の楽曲を収めた `'original_songs'` という表と、同じ楽曲の合成バージョンを収めた `'synth_songs'` という表を読み込みます。2 つの表を `"song_id"` で結合し、その結果を新しい W\&B 表 としてアップロードします。

```python theme={"system"}
import wandb

with wandb.init(project="my_project") as run:

    # 元の楽曲の表を取得
    orig_songs = run.use_artifact("original_songs:latest")
    orig_table = orig_songs.get("original_samples")

    # 合成した楽曲の表を取得
    synth_songs = run.use_artifact("synth_songs:latest")
    synth_table = synth_songs.get("synth_samples")

    # "song_id" をキーにして表を結合
    join_table = wandb.JoinedTable(orig_table, synth_table, "song_id")
    join_at = wandb.Artifact("synth_summary", "analysis")

    # 表をアーティファクトに追加して W&B にログする
    join_at.add(join_table, "synth_explore")
    run.log_artifact(join_at)
```

別々のアーティファクト オブジェクトに保存済みの 2 つの表を結合する方法の例については、[こちらのチュートリアル](https://forge.coreweave.com/wandb/stacey/cshanty/reports/Whale2Song-W-B-Tables-for-Audio--Vmlldzo4NDI3NzM)をご覧ください。


## Related topics

- [表をログする](/ja/products/wandb/tables/log_tables.md)