python-visuals

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

レポートを変更する場合は、すべて pbir を使用してください。 診断目的に限り、PBIR メタデータを読み取ります。pbir を利用できない場合、または必要な操作が用意されていない場合は、作業を中止して不足している操作を報告してください。レポート JSON を直接編集しないでください。

Python ビジュアルは、matplotlib／seaborn のスクリプトを実行して、Power BI キャンバスに静的な PNG 画像を描画します。構文が簡潔で、デフォルト設定も優れているため、raw matplotlib よりも seaborn を優先してください。ほとんどの種類のグラフを、より少ないコードで作成できます。

ビジュアルの識別情報

• visualType: pythonVisual
• データロール: Values（列とメジャー。複数指定できます）
• データ変数: dataset（自動で挿入される pandas DataFrame）
• 行数の上限: 150,000 行
• 出力: 72 DPI の静的 PNG（インタラクティブ機能はありません）

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

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

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

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

import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(8, 4))
ax.bar(dataset["Date"], dataset["Sales"], color="#5B8DBE")
ax.spines["top"].set_visible(False)
ax.spines["right"].set_visible(False)
plt.tight_layout()
plt.show()  # MANDATORY

重要なルール：

• plt.show() は最終行に必ず記述してください。これがないと何も描画されません
• dataset は pandas DataFrame として自動で挿入されます。作成しないでください
• 列名はフィールドバインディングの nativeQueryRef（表示名）と一致します
• 最後の plt.show() 呼び出しのみが描画されます。複数の図には対応していません

ステップ 2b：レビュー

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

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

pbir visuals python "Report.Report/Page.Page/PythonChart.Visual" \
  --script-file chart.py

CLI が PBIR 文字列のエスケープ処理を行います。

ステップ 4：検証する

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

PBIR 形式

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

{
  "source": {"expr": {"Literal": {"Value": "'import matplotlib.pyplot as plt\\n...\\nplt.show()'"}}},
  "provider": {"expr": {"Literal": {"Value": "'Python'"}}}
}

CLI がすべてのエスケープ処理を自動で行います。

対応ライブラリ

Power BI Service（Python 3.11）

パッケージ	バージョン	用途
matplotlib	3.8.4	主なプロット
seaborn	0.13.2	統計的な可視化
numpy	2.0.0	数値計算
pandas	2.2.2	データ操作
scipy	1.13.1	科学計算
scikit-learn	1.5.0	機械学習
statsmodels	0.14.2	統計モデル
pillow	10.4.0	画像処理

対応していないライブラリ： plotly、bokeh、altair（Service ではネットワーク接続がブロックされています）。

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

Desktop

ローカルにインストールされているパッケージは、制限なく使用できます。

ベストプラクティス

1. 必ず plt.show() を呼び出してください。必須であり、最終行に記述する必要があります
2. コンテナーのアスペクト比に合わせて figsize=(w, h) を使用してください（出力は 72 DPI）
3. グラフの装飾を取り除いてください。例：ax.spines["top"].set_visible(False) など
4. レポートのテーマに合わせた HEX カラーを使用してください
5. スクリプトはシンプルにしてください。タイムアウトは Desktop が 5 分、Service が 1 分です
6. 変換処理は最小限にしてください。負荷の高い計算は DAX／Power Query で行ってください
7. 本番環境のスクリプトでは、堅牢性を高めるために try/except を使用してください
8. 最初にデータをコピーしてください。操作する前に data = dataset.copy() を実行してください

制限事項

制約	Desktop	Service
出力	静的 PNG、72 DPI	静的 PNG、72 DPI
タイムアウト	5 分	1 分
行数の上限	150,000	150,000
ペイロード	--	30 MB
ネットワーク接続	制限なし	ブロック
ゲートウェイ	個人用のみ	個人用のみ
クロスフィルターの送信元	非対応	非対応
クロスフィルターの受信	対応	対応
Web への公開	非対応	非対応
埋め込み（アプリがデータを所有）	非対応	非対応

スクリプト構成テンプレート

import matplotlib.pyplot as plt
import numpy as np

# 1. Guard against empty data
if dataset.empty:
    fig, ax = plt.subplots(1, 1, figsize=(6, 4))
    ax.text(0.5, 0.5, "No data available", ha='center', va='center', fontsize=14, color='#888888')
    ax.axis('off')
    plt.show()
else:
    # 2. Data preparation (dataset is auto-injected)
    data = dataset.copy()

    # 3. Create figure with explicit size
    fig, ax = plt.subplots(figsize=(8, 4))

    # 4. Plot
    ax.plot(data["X"], data["Y"], color="#5B8DBE", linewidth=2)

    # 5. Style
    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)
    ax.grid(axis="y", alpha=0.3)

    # 6. Layout and render
    plt.tight_layout()
    plt.show()

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

次の条件をすべて満たす場合にのみ、Python ビジュアルを使用してください。

• ネイティブの同等機能がなく、妥当な Deneb 仕様も存在しない
• 値が、単に Vega で描ける図形ではなく、レンダリング時に実行する必要がある統計計算（モデルの適合、カーネル密度、予測帯など）にある
• ビジュアルをクロスフィルターのソース、ホバーツールチップ、publish-to-web、またはアプリ所有データの埋め込みに使用する必要がない
• レポートが、Fabric 対応リージョンの Pro／PPU 以上の容量で提供される

インタラクティブ性やクロスフィルターが重要な場合は、Deneb を使用してください（静的な PNG は選択ソースにはなりません）。小さなインラインマーク（スパークライン、バー、ステータスピル）が必要な場合は、SVG メジャーを使用してください（行数上限、タイムアウト、ライセンスやリージョンの制約がなく、publish-to-web でもレンダリングされます）。スクリプトビジュアルの用途は限定的です。社内または組織内で使用する、レンダリング時に統計計算を行うプロット向けです。

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

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

参考資料

• references/data-model.md -- dataset のグループ化の仕組み、行数／バイト数の上限、行単位の入力を強制する方法
• references/community-examples.md -- グラフの種類別に整理された seaborn ギャラリーの例、および matplotlib と Python Graph Gallery へのリンク
• references/chart-patterns.md -- よく使われる matplotlib／seaborn のグラフパターン（バー、ヒートマップ、ドーナツ、KPI、エリア）
• examples/script/ -- 単体で動作する Python スクリプト（bar-chart、trend-line）。エスケープ後、visual.json にすぐ注入できます
• examples/visual/bar-chart.json -- PBIR visual.json：PY 比較線と変化率ラベル付きの横積み棒グラフ
• examples/visual/kpi-card.json -- PBIR visual.json：値、変化率インジケーター、PY 比較を含むテキストベースの KPI
• examples/visual/trend-line.json -- PBIR visual.json：折れ線プロットと月単位の X 軸を含むエリアチャート

ドキュメントの取得

Python ビジュアル／パッケージのサポートに関する最新ドキュメントを取得するには、利用可能な場合は microsoft_docs_search と microsoft_docs_fetch（MCP）を使用し、それ以外の場合は mslearn search と mslearn fetch（CLI）を使用してください。ユーザーのリクエストに基づいて検索し、必要に応じて複数回検索して、作業を進める前に十分なコンテキストを確保してください。

関連スキル

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