レポートを編集する

W&B Report and Workspace API はパブリックプレビュー段階です。

このページでは、App UI から対話的に、または W&B SDK を使ってプログラムからレポートを編集する方法を説明します。プロット、run set、コードブロック、Markdown、HTML 要素、リッチメディアの追加方法に加え、run set のフィルタリングとグループ化、レポートのレイアウトの整理、多次元の関係の可視化についても取り上げます。レポートの本文は ブロック で構成されます。ブロックには、テキスト、画像、埋め込み可視化、experiments や run のプロット、パネルグリッドが含まれます。 パネルグリッド は、パネルと run set を保持する特殊な種類のブロックです。run set とは、W&B の project に記録された run の集合です。パネルは run set のデータを可視化したものです。

自分が所有するレポートを ARIA で修正するには、レポートを開いて Edit with ARIA をクリックし、変更したい内容を指示します。ARIA は変更内容を既存のレポートに保存します。

カスタマイズした保存済みワークスペースビューを作成する一連のチュートリアルについては、Programmatic workspaces notebook を実行してください。

プログラムからレポートを編集するには、W&B Python SDK に加えて W&B Report and Workspace API (wandb-workspaces) がインストールされている必要があります。

pip install wandb wandb-workspaces

プロットを追加する

プロットを使用すると、report 内で run データを可視化できます。各パネルグリッドには、run set とパネルの集合があります。パネルグリッド内の run set は、グリッド内のパネルに表示されるデータを制御します。別の run の集合からデータを取得するチャートを追加する場合は、新しいパネルグリッドを作成してください。

App UI
Report and Workspace API

report 内でスラッシュ (/) を入力すると、ドロップダウンメニューが表示されます。Add panelを選択してパネルを追加します。折れ線グラフ、散布図、平行座標チャートなど、W&B がサポートする任意のパネルを追加できます。

SDK を使用して、プログラムで report にプロットを追加します。1 つ以上のプロットまたはチャートのオブジェクトのリストを、Public API の PanelGrid クラスの panels パラメーターに渡します。対応する Python クラスを使用して、プロットまたはチャートのオブジェクトを作成します。次のサンプルでは、折れ線グラフと散布図を作成する方法を示します。

import wandb
import wandb_workspaces.reports.v2 as wr

report = wr.Report(
    project="report-editing",
    title="Report title",
    description="Report description.",
)

blocks = [
    wr.PanelGrid(
        panels=[
            wr.LinePlot(x="time", y="velocity"),
            wr.ScatterPlot(x="time", y="acceleration"),
        ]
    )
]

report.blocks = blocks
report.save()

プログラムで report に追加できるプロットとチャートの詳細については、wr.panels を参照してください。

run set を追加する

App UI または W&B SDK を使用して、project から run set をインタラクティブに追加します。

App UI
Report and Workspace API

レポートにスラッシュ (/) を入力すると、ドロップダウンメニューが表示されます。ドロップダウンから パネルグリッド を選択します。W&B は、レポートの作成元となった project から run set を自動的にインポートします。パネルをレポートにインポートすると、レポートは project から run 名を継承します。レポートでは、必要に応じて run のリネームを行い、読者に追加のコンテキストを提供できます。リネームは個々のパネルにのみ適用されます。同じレポート内でパネルをクローンすると、クローンされたパネルにも新しい名前が反映されます。

レポートで鉛筆アイコンをクリックし、レポートエディターを開きます。
run set で、リネームする run を見つけます。run 名にホバーし、action () メニューをクリックします。次のいずれかを選択し、フォームを送信します。
- Rename run for project: プロジェクト全体で run をリネームします。新しいランダム名を生成するには、フィールドを空白のままにします。
- Rename run for panel grid: レポート内でのみ run をリネームし、他のコンテキストでは既存の名前を保持します。このオプションでは新しいランダム名を生成できません。
Publish report をクリックします。

wr.Runset() および wr.PanelGrid クラスを使用して、project から run set を追加します。run set を追加するには、次の手順に従います。

wr.Runset() オブジェクトインスタンスを作成します。project パラメーターに run set を含む project の名前を、entity パラメーターに project を所有する entity を指定します。
wr.PanelGrid() オブジェクトインスタンスを作成します。runsets パラメーターに 1 つ以上の run set オブジェクトのリストを渡します。
1 つ以上の wr.PanelGrid() オブジェクトインスタンスをリストに保存します。
レポートインスタンスの blocks 属性をパネルグリッドインスタンスのリストで更新します。

次の例で [PROJECT-NAME] を W&B project 名に、 [ENTITY-NAME] を W&B entity 名に置き換えます。

import wandb
import wandb_workspaces.reports.v2 as wr

report = wr.Report(
    project="report-editing",
    title="Report title",
    description="Report description.",
)

panel_grids = wr.PanelGrid(
    runsets=[wr.RunSet(project="[PROJECT-NAME]", entity="[ENTITY-NAME]")]
)

report.blocks = [panel_grids]
report.save()

必要に応じて、SDK への 1 回の呼び出しで runset とパネルを追加できます。

import wandb

report = wr.Report(
    project="report-editing",
    title="Report title",
    description="Report description.",
)

panel_grids = wr.PanelGrid(
    panels=[
        wr.LinePlot(
            title="line title",
            x="x",
            y=["y"],
            range_x=[0, 100],
            range_y=[0, 100],
            log_x=True,
            log_y=True,
            title_x="x axis title",
            title_y="y axis title",
            ignore_outliers=True,
            groupby="hyperparam1",
            groupby_aggfunc="mean",
            groupby_rangefunc="minmax",
            smoothing_factor=0.5,
            smoothing_type="gaussian",
            smoothing_show_original=True,
            max_runs_to_show=10,
            plot_type="stacked-area",
            font_size="large",
            legend_position="west",
       ),
        wr.ScatterPlot(
            title="scatter title",
            x="y",
            y="y",
            # z='x',
            range_x=[0, 0.0005],
            range_y=[0, 0.0005],
            # range_z=[0,1],
            log_x=False,
            log_y=False,
            # log_z=True,
            running_ymin=True,
            running_ymean=True,
            running_ymax=True,
            font_size="small",
            regression=True,
        ),
    ],
    runsets=[wr.RunSet(project="[PROJECT-NAME]", entity="[ENTITY-NAME]")],
)


report.blocks = [panel_grids]
report.save()

run set を凍結する

report は project から最新のデータを表示するために run set を自動的に更新します。report 内の run set を特定の時点で凍結すると、その後の run が report の表示内容を変更しないようにできます。 report を表示しているときに run set を凍結するには、そのパネルグリッドの フィルター ボタンの近くにある雪の結晶アイコンをクリックします。

run set をプログラムからグループ化する

Workspace and Reports API を使用すると、run set 内の run をプログラムからグループ化できます。グループ化すると、関連する run がパネル内でまとめて表示され、設定や結果を比較しやすくなります。 run set 内の run は、設定値、run のメタデータ、またはサマリー指標でグループ化できます。次の表に、利用可能なグループ化方法と、それぞれの方法で使用できるキーを示します。

グループ化方法	説明	使用可能なキー
設定値	設定値で run をグループ化する	`wandb.init(config=)` の config パラメーターで指定した値
run のメタデータ	run のメタデータで run をグループ化する	`State`、`Name`、`JobType`
サマリー指標	サマリー指標で run をグループ化する	`wandb.Run.log()` で run にログした値

設定値で run をグループ化する

似た設定の run どうしを比較するには、設定値で run をグループ化します。設定値とは、run の設定 (wandb.init(config=)) で指定するパラメーターです。設定値でグループ化するには、config.[KEY] という構文を使用します。[KEY] には、グループ化に使用する設定値の名前を指定します。たとえば次のコードスニペットでは、まず group の設定値を指定して run を初期化し、続いてその group の設定値に基づいてレポート内の run をグループ化しています。[ENTITY] と [PROJECT] は、ご自身の W&B の entity 名とプロジェクト名に置き換えてください。

import wandb
import wandb_workspaces.reports.v2 as wr

entity = "[ENTITY]"
project = "[PROJECT]"

for group in ["control", "experiment_a", "experiment_b"]:
    for i in range(3):
        with wandb.init(entity=entity, project=project, group=group, config={"group": group, "run": i}, name=f"{group}_run_{i}") as run:
            # 学習を簡易的にシミュレートします
            for step in range(100):
                run.log({
                    "acc": 0.5 + (step / 100) * 0.3 + (i * 0.05),
                    "loss": 1.0 - (step / 100) * 0.5
                })

Python スクリプトまたはノートブック内では、config.group の値によって run をグループ化できます。

runset = wr.Runset(
  project=project,
  entity=entity,
  groupby=["config.group"]  # "group" の config の値で Group By
)

前の例の続きとして、グループ化した run set からレポートを作成できます。

report = wr.Report(
  entity=entity,
  project=project,
  title="Grouped Runs Example",
)

report.blocks = [
  wr.PanelGrid(
      runsets=[runset],
          )
      ]

report.save()

run のメタデータで run をグループ化する

メタデータで run をグループ化すると、ログに記録された値ではなく、run 固有のプロパティに基づいて整理できます。run の名前 (Name) 、state (State) 、ジョブタイプ (JobType) でグループ化できます。前の例の続きとして、次のコードスニペットを使うと、run を名前でグループ化できます。

runset = wr.Runset(
  project=project,
  entity=entity,
  groupby=["Name"]  # run 名でグループ化
)

run の名前は、wandb.init(name=) パラメーターで指定した名前です。名前を指定しない場合は、W&B が run にランダムな名前を割り当てます。run の名前は、W&B App の run の Overview ページで確認できるほか、プログラムから Api.runs().run.name で取得することもできます。

サマリー指標で run をグループ化する

以下のサンプルは、サマリー指標で run をグループ化する方法を示しています。サマリー指標とは、wandb.Run.log() で run にログした値のことです。run をログすると、W&B App の run の Overview ページにある Summary セクションで、サマリー指標の名前を確認できます。サマリー指標で run をグループ化する構文は summary.[KEY] です。[KEY] には、グループ化に使用するサマリー指標の名前を指定します。たとえば、acc というサマリー指標をログしたとします。[ENTITY] と [PROJECT] は、ご自身の W&B の entity 名とプロジェクト名に置き換えてください。

import wandb
import wandb_workspaces.reports.v2 as wr

entity = "[ENTITY]"
project = "[PROJECT]"

for group in ["control", "experiment_a", "experiment_b"]:
    for i in range(3):
        with wandb.init(entity=entity, project=project, group=group, config={"group": group, "run": i}, name=f"{group}_run_{i}") as run:
            # 学習をシミュレート
            for step in range(100):
                run.log({
                    "acc": 0.5 + (step / 100) * 0.3 + (i * 0.05),
                    "loss": 1.0 - (step / 100) * 0.5
                })

続いて、summary.acc のサマリー指標で run をグループ化できます。

runset = wr.Runset(
  project=project,
  entity=entity,
  groupby=["summary.acc"]  # サマリー値でグループ化
)

run set をプログラムでフィルタリングする

Workspace and Reports API を使用すると、run set をプログラムでフィルタリングし、レポートに追加できます。フィルタリングでは、設定値、メトリクス、タグ、run のプロパティに基づいて、表示したい特定の run だけに run set を絞り込みます。フィルタ式の基本的な構文は次のとおりです。

Filter('[KEY]') operation [VALUE]

この式において、[KEY] はフィルターの名前、operation は比較演算子 (例: >、<、==、in、not in、or、and) 、[VALUE] は比較対象の値です。Filter には適用したいフィルターの種類が入ります。利用可能なフィルターとその説明は次のとおりです。

フィルター	説明	利用可能なキー
`Config('[KEY]')`	設定値でフィルターする	`wandb.init(config=)` の `config` パラメーターで指定した値。
`SummaryMetric('[KEY]')`	サマリー指標でフィルターする	`wandb.Run.log()` で run にログした値。
`Tags('[KEY]')`	タグでフィルターする	run に追加したタグの値 (プログラムから、または W&B App で追加したもの) 。
`Metric('[KEY]')`	run のプロパティでフィルターする	`tags`、`state`、`displayName`、`jobType`

フィルターを定義したら、レポートを作成し、フィルター済みの run set を wr.PanelGrid(runsets=) に渡します。レポートにさまざまな要素をプログラムから追加する方法の詳細については、このページ内の Report and Workspace API タブを参照してください。次のサンプルは、レポート内で run set をフィルターする方法を示しています。角かっこで囲まれた値 (例: [ENTITY] や [PROJECT]) は、ご自身の値に置き換えてください。

Config フィルター

1 つ以上の config の値で run セットをフィルタリングします。config の値とは、run の設定 (wandb.init(config=)) で指定するパラメーターです。たとえば次のコードスニペットでは、まず learning_rate と batch_size の config の値を指定して run を初期化し、続いて learning_rate の config の値に基づいてレポート内の run をフィルタリングします。

import wandb

config = {
    "learning_rate": 0.01,
    "batch_size": 32,
}

with wandb.init(project="[PROJECT]", entity="[ENTITY]", config=config) as run:
    # ここに学習コードを記述します
    pass

Python スクリプトまたはノートブック内で、学習率が 0.01 を超える run をプログラムでフィルタリングできます。

import wandb_workspaces.reports.v2 as wr

runset = wr.Runset(
  entity="[ENTITY]",
  project="[PROJECT]",
  filters="Config('learning_rate') > 0.01"
)

and オペレーターを使用して、複数のconfig の値でフィルタリングすることもできます。

runset = wr.Runset(
  entity="[ENTITY]",
  project="[PROJECT]",
  filters="Config('learning_rate') > 0.01 and Config('batch_size') == 32"
)

前の例の続きとして、フィルタリングした run セットを使って次のようにレポートを作成できます。

report = wr.Report(
  entity="[ENTITY]",
  project="[PROJECT]",
  title="My Report"
)

report.blocks = [
  wr.PanelGrid(
      runsets=[runset],
      panels=[
          wr.LinePlot(
              x="Step",
              y=["accuracy"],
          )
      ]
  )
]

report.save()

メトリクスフィルター

run のタグ (tags) 、run の状態 (state) 、run 名 (displayName) 、ジョブタイプ (jobType) に基づいて run セットをフィルターします。

Metric フィルターは、他のフィルターとは異なる構文を使用します。値はリストとして渡す必要があります。

Metric('[KEY]') operation [VALUE]

たとえば、3 つの run を作成してそれぞれに名前を割り当てる、次の Python スニペットを考えてみます。

import wandb

with wandb.init(project="[PROJECT]", entity="[ENTITY]") as run:
    for i in range(3):
        run.name = f"run{i+1}"
        # ここに学習コードを記述します
        pass

レポートを作成する際に、実行を表示名でフィルタできます。たとえば、名前が run1、run2、run3 の実行を抽出するには、次のコードを使用します。

runset = wr.Runset(
  entity="[ENTITY]",
  project="[PROJECT]",
  filters="Metric('displayName') in ['run1', 'run2', 'run3']"
)

run の名前は、W&B App の run の Overview ページで確認できるほか、Api.runs().run.name を使ってプログラムから取得することもできます。

次のサンプルでは、run の state (finished、crashed、running) で run セットをフィルタリングする方法を示します。

runset = wr.Runset(
  entity="[ENTITY]",
  project="[PROJECT]",
  filters="Metric('state') in ['finished']"
)

runset = wr.Runset(
  entity="[ENTITY]",
  project="[PROJECT]",
  filters="Metric('state') not in ['crashed']"
)

SummaryMetric フィルター

サマリー指標で run set をフィルターすると、正解率や損失値など、特定の結果のしきい値を満たす run に絞り込めます。サマリー指標とは、wandb.Run.log() で run にログした値です。run をログした後は、W&B App で run の Overview ページにある Summary セクションから、サマリー指標の名前を確認できます。

runset = wr.Runset(
  entity="[ENTITY]",
  project="[PROJECT]",
  filters="SummaryMetric('accuracy') > 0.9"
)

runset = wr.Runset(
  entity="[ENTITY]",
  project="[PROJECT]",
  filters="Metric('state') in ['finished'] and SummaryMetric('train/train_loss') < 0.5"
)

タグフィルター

タグで run セットをフィルタリングすると、特定のタグを付けた run のみを表示できます。タグとは、run に追加する値のことで、プログラムから、または W&B App を使って追加します。

runset = wr.Runset(
  entity="[ENTITY]",
  project="[PROJECT]",
  filters="Tags('training') == 'training'"
)

コードブロックを追加する

結果とあわせて設定、サンプル、スニペットを共有するために、コードブロックを追加できます。App UI から対話型で追加することも、W&B SDK を使ってプログラムから追加することもできます。

App UI
Report and Workspace API

レポート内でスラッシュ (/) を入力すると、ドロップダウンメニューが表示されます。ドロップダウンから Code を選択します。コードブロック内のプログラミング言語名を選択すると、ドロップダウンが展開されます。ドロップダウンから使用するプログラミング言語の構文を選択します。JavaScript、Python、CSS、JSON、HTML、Markdown、YAML から選択できます。

wr.CodeBlock クラスを使用すると、プログラムからコードブロックを作成できます。language パラメーターと code パラメーターに、それぞれ言語名と表示するコードを指定します。次の例では、YAML ファイル内のリストを示します。

import wandb
import wandb_workspaces.reports.v2 as wr

report = wr.Report(project="report-editing")

report.blocks = [
    wr.CodeBlock(
        code=["this:", "- is", "- a", "cool:", "- yaml", "- file"], language="yaml"
    )
]

report.save()

これにより、次のようなコードブロックがレンダリングされます。

this:
- is
- a
cool:
- yaml
- file

次の例では、Python のコードブロックを示します。

report = wr.Report(project="report-editing")

report.blocks = [wr.CodeBlock(code=["Hello, World!"], language="python")]

report.save()

これにより、次のようなコードブロックがレンダリングされます。

Hello, World!

Markdown を追加する

レポート内のナラティブテキスト、見出し、インライン強調をフォーマットするために Markdown を追加します。App UI でインタラクティブに、または W&B SDK を使用してプログラム的に Markdown を追加できます。

App UI
Report and Workspace API

レポートにスラッシュ (/) を入力すると、ドロップダウンメニューが表示されます。ドロップダウンから Markdown を選択します。

wr.MarkdownBlock クラスを使用して、プログラム的に Markdown ブロックを作成します。text パラメーターに string を渡します：

import wandb
import wandb_workspaces.reports.v2 as wr

report = wr.Report(project="report-editing")

report.blocks = [
    wr.MarkdownBlock(text="Markdown cell with *italics* and **bold** and $e=mc^2$")
]

これにより、以下のような Markdown ブロックがレンダリングされます：

HTML 要素を追加する

見出しやリストなどの HTML 要素を追加して、レポートを構造化できます。App UI からインタラクティブに追加することも、W&B SDK を使ってプログラムから追加することもできます。

wandb.Image で画像をログすると、W&B は元のファイル名ではなく、media/images/[key]_[step]_[hash].png のようにコンテンツハッシュを含む生成された名前でファイルを保存します。そのため、元のファイル名を参照する <img> タグや Markdown 画像は解決されません。ログした画像をレポートに埋め込むには、まず画像をログし、生成されたファイルパスを画像の src の値として指定してください。

App UI
Report and Workspace API

レポート内でスラッシュ (/) を入力すると、ドロップダウンメニューが表示されます。ドロップダウンからテキストブロックのタイプを選択します。たとえば、H2 見出しブロックを作成するには、Heading 2 を選択します。

1 つ以上の HTML 要素のリストをレポートの blocks 属性に渡します。次の例では、H1、H2、および順序なしリストを作成する方法を示します。

import wandb
import wandb_workspaces.reports.v2 as wr

report = wr.Report(project="report-editing")

report.blocks = [
    wr.H1(text="How Programmatic Reports work"),
    wr.H2(text="Heading 2"),
    wr.UnorderedList(items=["Bullet 1", "Bullet 2"]),
]

report.save()

これにより、HTML 要素は次のようにレンダリングされます。

リッチメディアリンクの埋め込み

ツイート、動画、オーディオなどのリッチメディアを埋め込んで、レポートに外部コンテキストを追加できます。App UI または W&B SDK を使用してリッチメディアを埋め込めます。

App UI
Report and Workspace API

レポートに URL をコピー＆ペーストして、レポート内にリッチメディアを埋め込みます。以下のアニメーションは、Twitter、YouTube、SoundCloud から URL をコピー＆ペーストする方法を示しています。

Twitter

レポートに Tweet リンクの URL をコピー＆ペーストして、レポート内で Tweet を表示します。

YouTube

レポートに YouTube 動画の URL リンクをコピー＆ペーストして、動画を埋め込みます。

SoundCloud

SoundCloud リンクをコピー＆ペーストして、オーディオファイルをレポートに埋め込みます。

レポートの blocks 属性に 1 つ以上の埋め込みメディアオブジェクトのリストを渡します。以下の例は、動画と Twitter のメディアをレポートに埋め込む方法を示しています。

import wandb
import wandb_workspaces.reports.v2 as wr

report = wr.Report(project="report-editing")

report.blocks = [
    wr.Video(url="https://www.youtube.com/embed/6riDJMI-Y8U"),
    wr.Twitter(
        embed_html='<blockquote class="twitter-tweet"><p lang="en" dir="ltr">The voice of an angel, truly. <a href="https://twitter.com/hashtag/MassEffect?src=hash&amp;ref_src=twsrc%5Etfw">#MassEffect</a> <a href="https://t.co/nMev97Uw7F">pic.twitter.com/nMev97Uw7F</a></p>&mdash; Mass Effect (@masseffect) <a href="https://twitter.com/masseffect/status/1428748886655569924?ref_src=twsrc%5Etfw">August 20, 2021</a></blockquote>\n'
    ),
]
report.save()

パネルグリッドを複製する

パネルグリッドを複製すると、そのレイアウトを同じレポート内や別のレポートで再利用できます。パネルグリッドを選択してコピー＆ペーストすれば、同じレポート内で複製したり、別のレポートに貼り付けたりできます。右上隅のドラッグハンドルを選択すると、パネルグリッドのセクション全体を選択できます。クリックしたままドラッグすると、パネルグリッド、テキスト、見出しなど、レポート内の任意の範囲をハイライトして選択できます。

パネルグリッドの削除

レポート内でそのレイアウトやコンテンツが不要になったら、パネルグリッドを削除します。パネルグリッドを選択し、キーボードの delete キーを押すと削除できます。

ヘッダーを折りたたんでレポートを整理する

レポート内のヘッダーを折りたたむと、テキストブロック内のコンテンツを非表示にできます。レポートの読み込み時には、展開されているヘッダーのコンテンツのみが表示されます。ヘッダーを折りたたむことで、レポートのコンテンツを整理でき、必要以上のデータの読み込みを防げます。次のアニメーションは、その手順を示しています。

複数の次元にわたる関係を可視化する

3 つ以上の変数間の関係を 1 つのチャートで明らかにしたい場合、標準的な 2D プロットでは限界があります。2D プロットで表示できる変数よりも多くの変数を比較するには、色勾配を追加の次元として使用できます。変数の 1 つを色勾配で表現することで、パターンをより解釈しやすくなります。

penalty スコアや学習率など、色勾配で表現する変数を選択します。これにより、penalty (色) が reward や side effect (Y 軸) とどのように相互作用するかを、トレーニング時間 (X 軸) にわたってより明確に理解できます。
主要な傾向を強調表示します。特定の run のグループにホバーして、視覚化内でそれらを強調表示します。

​プロットを追加する

​run set を追加する

​run set を凍結する

​run set をプログラムからグループ化する

​設定値で run をグループ化する

​run のメタデータで run をグループ化する

​サマリー指標で run をグループ化する

​run set をプログラムでフィルタリングする

​Config フィルター

​メトリクスフィルター

​SummaryMetric フィルター

​タグフィルター

​コードブロックを追加する

​Markdown を追加する

​HTML 要素を追加する

​リッチメディアリンクの埋め込み

​Twitter

​YouTube

​SoundCloud

​パネルグリッドを複製する

​パネルグリッドの削除

​ヘッダーを折りたたんでレポートを整理する

​複数の次元にわたる関係を可視化する

プロットを追加する

run set を追加する

run set を凍結する

run set をプログラムからグループ化する

設定値で run をグループ化する

run のメタデータで run をグループ化する

サマリー指標で run をグループ化する

run set をプログラムでフィルタリングする

Config フィルター

メトリクスフィルター

SummaryMetric フィルター

タグフィルター

コードブロックを追加する

Markdown を追加する

HTML 要素を追加する

リッチメディアリンクの埋め込み

Twitter

YouTube

SoundCloud

パネルグリッドを複製する

パネルグリッドの削除

ヘッダーを折りたたんでレポートを整理する

複数の次元にわたる関係を可視化する