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

> 実験の run の構造化データを可視化してクエリできるように、W&B Tables を作成し、データを追加してログします。

# Tables をログする

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

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

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

Table を定義するには、データの各行に対して表示したい列を指定します。各行は、トレーニング用データセット内の 1 つの項目、トレーニング中の特定の step やエポック、テスト項目に対してモデルが行った予測、モデルによって生成されたオブジェクトなどを表します。各列には、数値、テキスト、ブール値、画像、動画、オーディオなどの固定のタイプがあります。タイプを事前に指定する必要はありません。各列に名を付け、その列インデックスにはそのタイプのデータだけを渡すようにしてください。より詳しい例については、[W\&B Tables ガイド](https://wandb.ai/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={null}
   wandb.Table(columns=["a", "b", "c"], data=[["1a", "1b", "1c"], ["2a", "2b", "2c"]])
   ```

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

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

```python theme={null}
# モデルが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)
```

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

表は変更可能です。スクリプトの実行中に、表へ最大 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 を使用できます。

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

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

```python theme={null}
# 表の列を定義する（各ラベルの信頼スコアを含む）
columns = ["id", "image", "guess", "truth"]
for digit in range(10):  # 各数字（0〜9）の信頼スコア列を追加する
    columns.append(f"score_{digit}")

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

# テストデータセットを反復処理し、表に行単位でデータを追加する
# 各行には画像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
    )  # 表に行データを追加する
```

<div id="adding-data-to-resumed-runs">
  #### 再開したrunにデータを追加する
</div>

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

```python theme={null}
import wandb

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

    # artifactから既存の表を読み込む
    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})
```

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

データが Table に入ったら、列単位または行単位でアクセスできます。

1. **行イテレータ**: `for ndx, row in table.iterrows(): ...` のように Table の行イテレータを使用して、データの各行を効率的に反復処理できます。
2. **列を取得する**: `table.get_column("col_name")` を使用してデータの列を取得します。必要に応じて、`convert_to="numpy"` を渡すと、その列をプリミティブ型の NumPy NDArray に変換できます。これは、列に `wandb.Image` のようなメディアタイプが含まれている場合に、元のデータへ直接アクセスするのに便利です。

<div id="save-tables">
  ## テーブルを保存する
</div>

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

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

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

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

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

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

  `wandb.Table.MAX_ARTIFACT_ROWS = X`

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

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

バックエンドでは、Tables は Artifacts として永続化されます。特定のバージョンにアクセスする場合は、artifact API を使用できます。

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

Artifacts の詳細については、Developer Guide の[Artifacts 章](/ja/models/artifacts/)を参照してください。

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

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

<div id="artifact-tables">
  ## Artifact テーブル
</div>

Workspace ではなく、run の Artifacts セクションに表をログするには、`artifact.add()` を使用します。これは、一度だけログし、その後の run から参照したいデータセットがある場合に便利です。

```python theme={null}
with wandb.init(project="my_project") as run:
    # 意味のある各stepに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 を、Artifacts と Tables を使って[表形式データのバージョン管理と重複排除を行う方法](https://wandb.me/TBV-Dedup)の例についてはこの Report を参照してください。

<div id="join-artifact-tables">
  ### Artifact テーブルを結合する
</div>

ローカルで作成したテーブルや、他の artifact から取得したテーブルは、`wandb.JoinedTable(table_1, table_2, join_key)` を使って結合できます。

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

artifact コンテキストで以前にログした 2 つの Table を結合するには、それらを artifact から取得し、その結果を新しい Table にまとめます。

たとえば、次のコード例は、`'original_songs'` という名前の元の楽曲の Table と、同じ楽曲の合成版を含む `'synth_songs'` という名前の別の Table を読み取る方法を示しています。このコードは 2 つのテーブルを `"song_id"` で結合し、結果のテーブルを新しい W\&B Table としてアップロードします。

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

    # 表をartifactに追加してW&Bにログする
    join_at.add(join_table, "synth_explore")
    run.log_artifact(join_at)
```

[このチュートリアル](https://wandb.ai/stacey/cshanty/reports/Whale2Song-W-B-Tables-for-Audio--Vmlldzo4NDI3NzM)を参照して、異なるArtifactオブジェクトに保存されている2つの既存の表を結合する方法の例を確認してください。