graphing

グラフ作成

プロットのコードはご自身で作成します。キットが提供するのは、すべてのチャートで統一すべき要素です。タイポグラフィ、背景色からのカラー導出、タイトルとキャプションのフレーム、オフライン HTML のパッケージ化が含まれます。チャート自体については、目の前のデータを踏まえてご自身で判断してください。

基本要素

このスキルの scripts/ ディレクトリを sys.path に追加して、chartkit をインポートします。作業ディレクトリはユーザーのプロジェクトであるため、相対パスではなく絶対パスを使用してください。以下の例では /path/to/graphing/scripts と記載しています。実際のパスに置き換えてください。

関連する基本要素：

• theme(bg, font)：matplotlib の rcParams を設定し、解決済みの色を返します。前景色は背景の輝度から導出されるため、bg が暗色でもチャートは正しく暗色になります。フィールド：bg dark text muted grid spine accent secondary series font_css。
• palette(n, base)：n 色を返します。base を指定しない場合はデフォルトの系列色を順に使用し、16 進数の base を指定するとそこから色のランプを作成し、リストを指定するとリスト内の色を順に使用します。
• finish(ax, title, subtitle, source)：タイポグラフィのフレームです。左揃えの太字タイトル、控えめな色のサブタイトル、小さな出典キャプションを設定します。
• save(fig, stem, formats, dpi)：stem.png、stem.svg、または両方を書き出します。パスを返します。
• write_html(out, data, component_js, title, bg, font)：自己完結型のインタラクティブページを作成します。third_party/ から React、ReactDOM、react-is、Recharts をインライン化するため、ファイルをオフラインで開けます。コンポーネントは window.__CHART_DATA__ を読み込み、#root に描画します。
• zero_fill_days(pairs) rolling_mean(values, w) log_floor(values)：以下で説明する注意点に対処するための小さなデータヘルパーです。適切な場合にのみ使用してください。

手順

1. データを確認し、どのような表現が適切か判断します。 形状、件数、意味に基づいて選びます。時間の経過に伴う傾向には折れ線または日ごとの棒グラフ、順位付きカテゴリには横棒グラフ、少数の項目で全体に占める割合を示すには円グラフ、相関には散布図が適しています。これらに限られるわけではありません。積み上げ面グラフ、二軸グラフ、スモールマルチプル、しきい値の注釈など、すべてコードで作成できます。

2. 状況から色を推測します。 会話やメモリを確認し、Tailwind の設定、CSS 変数、ブランドガイドラインなどのデザイン上の手がかりを探します。また、データの意味（エラーには赤やアンバー、成功には緑など）も考慮します。背景色を theme(bg=...) に、ブランドカラーを palette(base=...) または直接指定します。推測できる情報がない場合にのみ、デフォルトを使用します。フォントはデフォルトで Inter を使用し、ユーザーが書体を指定した場合、または出力先に文書化されたブランドフォントがある場合にのみ変更します。

3. スクラッチパッドに短いスクリプトを記述します。chartkit をインポートし、matplotlib（またはインタラクティブな出力の場合は Recharts コンポーネント）で図を作成し、finish を呼び出して保存します。

4. レンダリングして結果を確認します。 渡す前に PNG を読み込み、自分の目で確認します。ラベルが読みやすいか、重なりがないか、色を見分けられるか、データの特徴が実際に伝わるかを確認してください。適切になるまで修正して再レンダリングします。

チャートスクリプトの形式

matplotlib を使った PNG または SVG：

import sys
sys.path.insert(0, "/path/to/graphing/scripts")
import chartkit as ck
import matplotlib.pyplot as plt

c = ck.theme()                       # or theme(bg="#0f1419") for a dark surface
fig, ax = plt.subplots(figsize=(10, 5))
# ...plain matplotlib against the data, using c.accent, c.secondary, ck.palette(...)
ck.finish(ax, title="What the chart shows", subtitle="scope or time range",
          source="source: where the data came from, date")
print(ck.save(fig, "out/report", formats=("png", "svg")))

Recharts を使ったインタラクティブ HTML。JSX やビルド手順は使わず、プレーンな React.createElement で記述します。

component = """
(function () {
  var e = React.createElement
  var R = window.Recharts
  var DATA = window.__CHART_DATA__
  function App() {
    return e(R.ResponsiveContainer, { width: "100%", height: 420 },
      e(R.LineChart, { data: DATA },
        e(R.CartesianGrid, { stroke: "GRID", vertical: false }),
        e(R.XAxis, { dataKey: "x" }), e(R.YAxis, null),
        e(R.Tooltip, null),
        e(R.Line, { dataKey: "y", stroke: "ACCENT", strokeWidth: 2.4,
                    dot: false, isAnimationActive: false })))
  }
  ReactDOM.createRoot(document.getElementById("root")).render(e(App))
})()
"""
ck.write_html("out/report.html", data, component, title="What the chart shows")

コンポーネント内の色をテーマの実際の色に置き換え、isAnimationActive: false を維持してください。これにより、ファイルを開いた瞬間にチャートが完成した状態で表示されます。

判断で決めるものであり、フラグで決めるものではありません

以下は、適切なチャートのデフォルト設定です。データが別の設定を求める場合は変更してください。

• x 軸ラベルが重なる場合にのみ回転させます。短いラベルは水平のままにします。
• カテゴリが少ない場合は、棒の幅に上限を設けます。棒が 2 本なら、キャンバスの端から端まで埋めないようにします。
• カテゴリがおよそ 12 個以下の場合は、棒に値を表示します。軸とグリッド線は傾向を読み取るためのものであり、正確な値を示すためのものではありません。
• 自然な順序がある場合を除き、カテゴリ別の棒は値の順に並べます。
• カテゴリ名が長い場合は、横棒グラフのほうが読みやすくなります。
• タイトルにはチャートが示す内容を記載します。サブタイトルには期間や対象範囲を記載します。データソースのキャプションには、データの出典と取得時期を記載します。省略する場合は、意図的に行ってください。
• 凡例は複数の系列がある場合にのみ使用します。単一の系列はタイトルで示します。
• 重要な情報をチャートに注釈します。デプロイを示す線、しきい値、ピーク、ユーザーが尋ねた異常値などです。読者に不要な注釈はごちゃつきの原因になります。

ヘルパーがある理由となる注意点

• カレンダー上の欠損：欠損日がある時系列を連続軸に表示すると、誤解を招きます。zero_fill_days は欠損日をゼロで埋めます。ゼロで埋めると誤解を招く場合（イベントがないのではなく、サンプリングがまばらな場合など）は使用しないでください。
• 移動平均：rolling_mean は後方に適用され、序盤の点はその時点までに存在する値の平均になります。今日で終わるデータに対して、中央に配置しないでください。
• 対数スケール：値が軸の最小値と等しい棒は、高さがゼロになります。log_floor は 1 桁下の下限を設定します。
• 負の値：matplotlib は負の値を処理できますが、y 軸の範囲に負の値が含まれていることを確認し、棒が正負の両方向に伸びる場合はゼロ線を追加してください。Recharts の y 軸の範囲はデフォルトで 0 から始まるため、データに負の値がある場合や対数スケールの場合は、YAxis に明示的な domain を渡してください。

検証

最小限のレンダリングを実行し、結果を確認してください。

python3 -c "
import sys
sys.path.insert(0, '/path/to/graphing/scripts')
import chartkit as ck
import matplotlib.pyplot as plt
c = ck.theme()
fig, ax = plt.subplots(figsize=(8, 4))
ax.bar(['A', 'B', 'C'], [10, 30, 20], color=c.accent, width=0.5)
ck.finish(ax, title='chartkit smoke test')
print(ck.save(fig, '/tmp/ck_smoke'))
"

空でない PNG が書き出されたことを確認してから、読み戻して正しくレンダリングされることを確認してください。