r-visuals

Power BI の R ビジュアル（PBIR）

レポートを変更する際は、必ず pbir を使用してください。 PBIR メタデータは診断にのみ読み取ってください。pbir を利用できない場合、または必要な操作がない場合は、そこで停止して不足している機能を報告してください。レポート JSON を直接編集してはいけません。

R ビジュアルは、R スクリプト（主に ggplot2）を実行して、Power BI キャンバスに静的な PNG 画像を描画します。推奨ライブラリは ggplot2 です。文法に基づいたグラフィックスのアプローチにより、少ないコードで、すっきりとした出版品質の統計ビジュアライゼーションを作成できます。R は特に統計ビジュアライゼーションに優れています。

ビジュアルの識別情報

• visualType: scriptVisual
• データロール: Values（列とメジャー。複数指定可能）
• データ変数: dataset（data.frame、自動で挿入）
• 行数制限: 150,000 行
• 出力: 72 DPI の静的 PNG — インタラクティブではありません

ワークフロー：R ビジュアルの作成

ステップ 1：ビジュアルを追加する

pbir add visual scriptVisual "Report.Report/Page.Page" --name RevenueByDateR \
  --data "Values:Sales.Date" --data "Values:Sales.Revenue"

ステップ 2：スクリプトを記述する

library(ggplot2)

p <- ggplot(dataset, aes(x=Date, y=Sales)) +
  geom_col(fill="#5B8DBE") +
  theme_minimal(base_size=12) +
  theme(panel.grid.major.x=element_blank())

print(p)  # MANDATORY for ggplot2

重要なルール：

• ggplot2 オブジェクトでは print(p) が必須です。Power BI では自動的に表示されません。
• dataset は data.frame として自動で挿入されます。作成する必要はありません。
• 名前のエスケープに関する問題を避けるため、列にはインデックス（dataset[,1]）でアクセスしてください。
• スペースを含む列名にはバッククォートを使用してください：dataset$`Order Lines`

ステップ 2b：レビューする

スクリプトをユーザーに提示する前に、r-reviewer エージェントを呼び出し、正確性を検証してデザインに関するフィードバックを得てください。

ステップ 3：スクリプトを挿入する

pbir visuals r "Report.Report/Page.Page/RevenueByDateR.Visual" --script-file chart.r

PBIR の文字列エスケープは CLI が処理します。

ステップ 4：検証する

pbir visuals bind "Report.Report/Page.Page/RevenueByDateR.Visual" --show
pbir validate "Report.Report" --all

PBIR の形式

読み取り専用の診断では、スクリプトは visual.objects.script[0].properties に格納されています。

{
  "source": {"expr": {"Literal": {"Value": "'library(ggplot2)\\n...\\nprint(p)'"}}},
  "provider": {"expr": {"Literal": {"Value": "'R'"}}}
}

visualType が scriptVisual、provider が 'R' である点を除き、Python ビジュアルと同じ構造です。

対応パッケージ

Power BI Service（R 4.3.3）

パッケージ	バージョン	用途
ggplot2	3.5.1	文法に基づいたグラフィックス
dplyr	1.1.4	データ操作
tidyr	1.3.1	データの整理
ggrepel	0.9.5	重ならないラベル
patchwork	1.2.0	複数のプロットを組み合わせる
cowplot	1.1.3	出版品質のプロット
corrplot	0.94	相関行列
viridis	0.6.5	カラースケール
RColorBrewer	1.1-3	カラーパレット
forecast	8.23.0	時系列予測
pheatmap	1.0.12	ヒートマップ
treemap	2.4-4	ツリーマップ
lattice	0.22-6	トレリスグラフィックス

約 1000 個の CRAN パッケージを利用できます。サポート対象外： ネットワーク接続を必要とするパッケージ（RgoogleMaps、mailR）。

パッケージの一覧：https://learn.microsoft.com/power-bi/connect-data/service-r-packages-support

Desktop

ローカルにインストールされた R パッケージは、制限なく利用できます。R は別途インストールする必要があります。

ベストプラクティス

1. 必ず print(p) を呼び出してください — ggplot2 オブジェクトは明示的に出力する必要があります。
2. データが空の場合に備えてください — if (nrow(dataset) == 0) { plot.new(); text(0.5, 0.5, "No data") }
3. インデックスを使って列にアクセスしてください — dataset[,1] を使うと、名前のエスケープに関する問題を避けられます。
4. theme_minimal() を使用してください — Power BI との相性がよい、すっきりとした外観になります。
5. カテゴリ変数をファクターにしてください — factor() を使って並べ替え順を明示的に制御します。
6. レポートのテーマに合った 16 進カラーコードを使用してください。
7. 余白を設定してください — plot.margin=margin(t, r, b, l) を使うと、クリッピングを防げます。
8. スクリプトを簡潔に保ってください — タイムアウトは Desktop で 5 分、Service で 1 分です。

制限事項

制約	Desktop	Service
出力	72 DPI の静的 PNG	72 DPI の静的 PNG
タイムアウト	5 分	1 分
行数制限	150,000	150,000
出力サイズ	2 MB	30 MB
ネットワーク接続	制限なし	ブロック
ゲートウェイ	個人用のみ	個人用のみ
クロスフィルターの送信元	サポートされていません	サポートされていません
クロスフィルターの受信	対応	対応
Web への公開	サポートされていません	サポートされていません
埋め込み（app-owns-data）	サポートされていません	サポートされていません

スクリプト構造のテンプレート

library(ggplot2)

# 1. Guard against empty data
if (nrow(dataset) == 0) {
  plot.new()
  text(0.5, 0.5, "No data available", cex=1.5)
} else {
  # 2. Data preparation (index-based access)
  df <- data.frame(
    category = dataset[,1],
    value = dataset[,2]
  )

  # 3. Create visualization
  p <- ggplot(df, aes(x=reorder(category, -value), y=value)) +
    geom_col(fill="#5B8DBE", width=0.7) +
    theme_minimal(base_size=12) +
    theme(
      panel.grid.major.x = element_blank(),
      axis.title = element_blank()
    )

  # 4. Render
  print(p)
}

R と Python の構文リファレンス

言語選択の判断については、上記の「スクリプトビジュアルを使用する場合」セクションを参照してください。この表では、すでに R を使用すると決めたスクリプトの機械的な構文の違いのみを説明します。

項目	R (scriptVisual)	Python (pythonVisual)
描画呼び出し	print(p)	plt.show()
列へのアクセス	dataset[,1] または dataset$col	dataset.iloc[:,0] または dataset["col"]
空データのチェック	if (nrow(dataset) == 0)	if len(dataset) == 0:
因子／カテゴリの順序	factor(x, levels=...)	pd.Categorical(x, categories=...)
実行環境（Service）	R 4.3.3	Python 3.11

スクリプトビジュアルを使用する場合

R ビジュアルを選ぶのは、次のすべてに該当する場合に限ります。

• グラフにネイティブの同等機能がなく、妥当な Deneb 仕様もない
• 値が、単に Vega で描画できる形状ではなく、描画時に実行する必要がある統計計算（モデルの当てはめ、カーネル密度、予測帯など）によるものである
• ビジュアルをクロスフィルターのソース、ホバーツールヒント、Web への公開、またはアプリ所有データの埋め込みに使用する必要がない
• レポートが Pro／PPU 以上の容量で、Fabric 対応リージョンに配信される

インタラクティブ性やクロスフィルターが重要な場合は、Deneb を使用してください（静的 PNG は選択元にできません）。小さなインラインマーク（スパークライン、バー、ステータスピルなど）が必要な場合は、SVG メジャーを使用してください（行数上限、タイムアウト、ライセンス／リージョン制限がなく、Web への公開でもレンダリングされます）。スクリプトビジュアルの用途は限られています。つまり、社内または組織内で使用する、描画時に計算する統計グラフです。

スクリプトビジュアルを使う判断が妥当な場合の R と Python の選択： 出版品質の統計的な既定値や、Python に同等のパッケージがないパッケージ（forecast、corrplot、pheatmap、リッジライン／バイオリン）を使う場合は R を使用してください。計算で scikit-learn、statsmodels、または scipy を主に使う場合や、レポートの周辺ロジックがすでに Python の場合は Python を使用してください。どちらでも同等の場合は、レポート内の他のスクリプトで使われている言語を既定にしてください。言語を混在させると、公開時に検証するパッケージの範囲が倍増します。

グラフの種類が「統計的に見える」という理由だけで、スクリプトビジュアルを既定にしないでください。箱ひげ図、ロリポップチャート、ダンベルチャートには SVG メジャーまたは Deneb を使用し、実際に計算を行うグラフに限ってスクリプトを使用してください。

参考資料

• references/data-model.md -- dataset のグループ化の仕組み、行数／バイト数の上限、行ごとの入力を強制する方法、R 固有の注意点（Time 型、テキスト描画フラグ、CJK フォント）
• references/community-examples.md -- グラフの種類別にまとめた R Graph Gallery の例（分布、相関、ランキング、推移、フロー）
• references/ggplot2-patterns.md -- よく使われる ggplot2 グラフのパターン（バー、ドーナツ、折れ線、ヒートマップ、ブレット）
• examples/script/ -- 単独で実行できる R スクリプト（棒グラフ、トレンドライン）。エスケープ処理後、visual.json にそのまま挿入できます
• examples/visual/bullet-chart.json -- PBIR visual.json：条件付き色分け、エラー処理、広範なエスケープ処理を含むブレットチャート
• examples/visual/bar-chart.json -- PBIR visual.json：PY 比較線と色付きのアカウントラベルを含む横棒グラフ
• examples/visual/trend-line.json -- PBIR visual.json：リボンプロットと月の因子処理を含む面グラフ

ドキュメントの取得

R ビジュアル／パッケージの最新のサポート情報を取得するには、https://learn.microsoft.com を検索し、該当するページを取得してください。ユーザーのリクエストに基づいて検索し、十分な情報を得てから作業を進められるよう、必要に応じて複数回検索してください。

関連スキル

• pbi-report-design -- レイアウトとデザインのベストプラクティス
• python-visuals -- Python スクリプトビジュアル（同じ概念で、言語が異なります）
• deneb-visuals -- Vega／Vega-Lite ビジュアル（インタラクティブで、ベクターベースの代替手段）
• svg-visuals -- DAX メジャーを使った SVG（軽量なインライングラフィック）
• pbir-format（pbip プラグイン）-- PBIR JSON 形式のリファレンス