ncukondo avatar

quarto-survey-analysis

Quarto アンケート分析 - CSVアンケートデータからQuarto+Pythonパイプラインで統計集計・可視化・PDFレポート・PPTXスライドを生成

Install

/plugin install quarto-survey-analysis@agent-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ncukondo/agent-plugins.

Contents

Discovered from source

Skills 2

Quarto アンケート分析プロジェクト環境構築

CSV アンケートデータを分析するための Quarto + Python プロジェクトをゼロから構築する。

目次

  1. 前提チェック
  2. ディレクトリ構成作成
  3. pyproject.toml 生成
  4. _quarto.yml 生成
  5. WSL検出・.mise.toml 生成
  6. .gitignore/.python-version 生成
  7. uv sync
  8. CLAUDE.md 生成

進捗チェックリスト

- [ ] Step 1: 前提チェック(uv, quarto)
- [ ] Step 2: ディレクトリ構成作成
- [ ] Step 3: pyproject.toml + run_commands.py 生成
- [ ] Step 4: _quarto.yml 生成
- [ ] Step 5: WSL検出・.mise.toml 生成(該当時)
- [ ] Step 6: .gitignore, .python-version 生成
- [ ] Step 7: uv sync 実行
- [ ] Step 8: CLAUDE.md 生成

ステップ1: 前提チェック

uv と quarto の存在を確認する。いずれかが存在しない場合、インストール手順を案内して中断する。

uv --version
quarto --version

ステップ2: ディレクトリ構成作成

引数 [project-name] をディレクトリ名として使用する。既にプロジェクトディレクトリにいる場合はカレントディレクトリを使う。

mkdir -p data output/figures output/tables

ステップ3: pyproject.toml 生成

{project-name} を実際のプロジェクト名に置換して作成する:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["."]

[project]
name = "{project-name}"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "pandas>=2.2",
    "matplotlib>=3.9",
    "matplotlib-fontja>=1.1",
    "jupyter>=1.0",
    "ipykernel>=6.29",
    "nbformat>=5.10",
    "nbclient>=0.10",
    "python-pptx>=1.0",
]

[project.scripts]
render = "run_commands:render"
preview = "run_commands:preview"

同時に run_commands.py をプロジェクトルートにコピーする:

cp "$SKILL_ROOT/scripts/run_commands.py" .

ステップ4: _quarto.yml 生成

日本語 Typst PDF 出力用の Quarto 設定を作成する:

project:
  title: "{project-name}"
  type: default
  output-dir: output
  preview:
    port: 4200

format:
  typst:
    toc: true
    toc-depth: 3
    number-sections: true
    mainfont: "Yu Gothic"
    fontsize: 10pt
    papersize: a4
    margin:
      x: 2cm
      y: 2cm
    lang: ja
    columns: 1

execute:
  echo: false
  warning: false

ステップ5: WSL 検出と .mise.toml 生成

WSL 環境(パスが /mnt/ で始まる)では、venv をユーザーディレクトリに配置する。Windows ファイルシステム上の venv はパフォーマンスが著しく低下するため。

pwd | grep -q "^/mnt/" && echo "WSL" || echo "native"

WSL の場合、.mise.toml を作成する:

[env]
_.python.venv = "{{env.HOME}}/.venvs/{project-name}"
UV_PROJECT_ENVIRONMENT = "{{env.HOME}}/.venvs/{project-name}"

ネイティブ Linux / macOS の場合、.mise.toml は不要(デフォルトの .venv/ を使用)。

ステップ6: .gitignore と .python-version 生成

.gitignore:

# Output
output/

# Python
__pycache__/
*.pyc
.venv/

# Quarto
.quarto/
/.quarto/

# Jupyter
.ipynb_checkpoints/

.python-version:

3.13

ステップ7: uv sync 実行

uv sync

mise を使用している場合は先に mise trust を実行:

mise trust && uv sync

ステップ8: CLAUDE.md 生成

$SKILL_ROOT/templates/CLAUDE.md を参考に、プロジェクト固有の CLAUDE.md を作成する。テンプレート内の汎用記述をプロジェクトの実情に合わせて調整する。

# テンプレートを確認
cat "$SKILL_ROOT/templates/CLAUDE.md"

完了確認

以下をユーザーに報告する:

  1. 作成されたファイル一覧
  2. uv sync の成否
  3. 次のステップ: data/ に CSV を配置し、/survey-report-builder でレポート構築

注意事項

  • Jupyter カーネルはカスタム名を使わず python3 に自動解決させる(ポータブル性のため)
  • WSL 環境では必ず venv をユーザーディレクトリに逃がす
  • uv run render / uv run preview がすぐ使えることを確認する
  • output/ ディレクトリは .gitignore に含める

アンケート分析レポート構築

data/ に配置された CSV アンケートデータから、Quarto レポート(PDF)と発表用スライド(PPTX)を構築する。

目次

  1. 前提チェック・CSV読み込み
  2. 列の分類
  3. metadata.json 作成
  4. index.qmd 構築
  5. スクリプト追加
  6. quarto render
  7. PPTX生成(任意)

進捗チェックリスト

- [ ] Step 1: 前提チェック・CSV読み込み・列構造把握
- [ ] Step 2: ユーザーと列分類を確認
- [ ] Step 3: exam_metadata.json 作成
- [ ] Step 4: index.qmd 構築(setup → セクション)
- [ ] Step 5: pyproject.toml にスクリプト追加
- [ ] Step 6: quarto render → エラー修正 → 再render
- [ ] Step 7: PPTX スライド生成(該当時)

ステップ1: 前提チェックとCSV読み込み

まず前提条件を確認する:

uv --version && quarto --version
python -c "import pandas; import matplotlib; print('OK')"

いずれかが失敗する場合は /quarto-survey-setup を先に実行するよう案内する。

次に引数 [csv-file-path] を読み込み、列構造を把握する:

import pandas as pd
df = pd.read_csv("[csv-file-path]", encoding="utf-8-sig")
print(f"回答数: {len(df)}, 列数: {len(df.columns)}")
for col in df.columns:
    print(f"  {col}: {df[col].nunique()} unique, {df[col].isna().mean()*100:.0f}% missing")

ステップ2: 列の分類

各列を以下の4カテゴリに分類する。必ずユーザーに確認しながら進める:

カテゴリ判定基準分析方法
タイムスタンプ日時形式回答期間の算出のみ
Likert尺度5段階の順序カテゴリ度数分布 + 横棒グラフ + クロス集計
カテゴリ有限個の名義変数度数分布 + 横棒グラフ
自由記述テキスト長が長い / ユニーク値が多いキーワード分類 + 質的分析

ユーザーへの確認事項:

  • 各列がどのカテゴリに該当するか
  • Likert尺度の順序(ネガティブ→ポジティブ or 逆)
  • クロス集計に使用する属性列
  • 自由記述のキーワード分類ルール

ステップ3: data/exam_metadata.json 作成

ユーザーからのヒアリングを基にメタデータ JSON を作成する:

{
  "exam": {
    "name": "試験・調査の名称",
    "date": "YYYY-MM-DD",
    "date_display": "YYYY年MM月DD日(曜日)"
  },
  "survey": {
    "target": "対象者の説明",
    "target_total": 0,
    "respondents": 0,
    "response_rate": 0.0
  },
  "label_map": {
    "column_name": "日本語表示ラベル"
  }
}

label_map: CSV の全列名をキーとし、日本語表示ラベルを設定する。グラフのタイトル・凡例・軸ラベルで使用される。

ステップ4: index.qmd 構築

4-1. YAML ヘッダ

---
title: "レポートタイトル"
subtitle: "サブタイトル"
date: today
editor:
  render-on-save: true
---

4-2. setup ブロック

以下を含む setup コードブロックを作成する:

#| label: setup
#| include: false

import json
import pandas as pd
import matplotlib
import matplotlib.pyplot as plt
from pathlib import Path

matplotlib.rcParams["svg.fonttype"] = "none"
matplotlib.rcParams["figure.dpi"] = 150
matplotlib.rcParams["font.family"] = "Yu Gothic"

OUTPUT_DIR = Path("output")
FIGURES_DIR = OUTPUT_DIR / "figures"
TABLES_DIR = OUTPUT_DIR / "tables"
FIGURES_DIR.mkdir(parents=True, exist_ok=True)
TABLES_DIR.mkdir(parents=True, exist_ok=True)

4-3. ヘルパー関数

setup ブロック内に以下の4関数を定義する。実装は $SKILL_ROOT/scripts/helpers.py を参照してそのままコピーする:

# ヘルパー関数の実装を確認
cat "$SKILL_ROOT/scripts/helpers.py"
関数用途
save_summary(series, name, label)度数分布表の CSV 保存
plot_horizontal_bar(series, title, order, name, ...)横棒グラフ(件数・割合ラベル付き)
plot_cross_tab(df, row_col, col_col, ...)クロス集計の積み上げ棒グラフ
save_table_svg(df, name, title, ...)DataFrame のテーブル SVG 化

カラーパレットも helpers.py に定義済み:

  • COLORS — 10色メインパレット
  • DIFFICULTY_CMAP — 5段階 Likert 用(ネガティブ→ポジティブ)

4-4. セクション構成

index.qmd の本文を以下の順序で構成する。各セクションは独立した Quarto コードブロックとする:

A. はじめに

  • 調査の概要説明テキスト
  • 試験・調査概要テーブル(save_table_svg() 使用)
  • アンケート概要(対象者数、回答率、回答期間)

B. 回答者の属性

  • 属性列ごとに save_summary() + plot_horizontal_bar()
  • 属性同士のクロス集計(plot_cross_tab())

C. 各設問の集計・可視化

  • Likert尺度: 順序定義 → save_summary() → plot_horizontal_bar() → plot_cross_tab()
  • カテゴリ: save_summary() + plot_horizontal_bar()(自由記述混合時は正規化関数を定義)

D. 自由記述の分析

  • キーワードマッチングによる分類関数を定義
  • 複数カテゴリ該当の処理(1回答 → 複数カテゴリ)
  • 「なし」「特になし」系の事前除外
  • 分類結果の横棒グラフ + 利用率スタック棒グラフ

E. 質的分析セクション(テーマ分析がある場合)

  • output/improvement_qualitative.csv を読み込み
  • テーマ別件数の横棒グラフ + 代表的引用一覧

F. まとめ

  • 各設問の主要所見を自動集計・出力(最頻値・割合を動的算出)

4-5. コードブロックの規約

#| label: fig-{topic}          # 図の場合
#| label: {topic}              # テキスト出力の場合
#| fig-cap: "キャプション"     # 図の場合
#| output: asis                # Markdown テキスト出力の場合
#| include: false              # setup ブロックのみ

ステップ5: pyproject.toml にスクリプトを追加

[project.scripts] に以下を追加(まだ存在しない場合):

[project.scripts]
render = "run_commands:render"
preview = "run_commands:preview"

質的分析から PPTX を生成する場合:

slides = "generate_theme_slides:main"

ステップ6: quarto render でPDF生成

uv run render

エラー時のフィードバックループ: エラーが出たら修正して再度 render する。よくあるエラー:

  • KeyError: 列名が CSV と不一致 → df.columns で確認
  • FileNotFoundError: データファイルのパス誤り
  • フォントエラー: matplotlib-fontja 未インストール → uv sync

ステップ7: PPTX スライド生成(任意)

質的分析結果がある場合、$SKILL_ROOT/scripts/generate_theme_slides.py を参考にスライド生成スクリプトを作成する:

# スクリプトの実装を確認
cat "$SKILL_ROOT/scripts/generate_theme_slides.py"

プロジェクトルートにコピーしてデータパスを調整する。前提ファイル:

  • output/improvement_qualitative.csv — 質的分析コーディング結果
  • output/summary_improvement_themes.csv — テーマ別集計

出力規約

ファイル命名

種類パス命名規則
度数分布 CSVoutput/summary_{topic}.csv列名に対応
クロス集計 CSVoutput/summary_{topic}_cross.csv行列列名を結合
横棒グラフ SVGoutput/figures/{topic}.svg列名に対応
テーブル SVGoutput/tables/{topic}.svgテーブル名に対応
ID付き全回答output/responses_with_id.csv固定名
自由記述抜粋output/free_text.csv固定名
PPTXoutput/{topic}.pptxテーマ名に対応

CSV フォーマット

  • エンコーディング: UTF-8 with BOM (encoding="utf-8-sig") — Excel互換

SVG 設定

  • matplotlib.rcParams["svg.fonttype"] = "none" — テキスト要素を保持
  • フォント: Yu Gothic(日本語対応)
  • DPI: 150

自由記述のキーワード分類パターン

def classify_responses(text):
    """自由記述を複数カテゴリに分類する."""
    text_lower = str(text).lower()
    categories = []
    if "キーワードA" in text or "keyword_a" in text_lower:
        categories.append("カテゴリA")
    if "キーワードB" in text:
        categories.append("カテゴリB")
    if not categories:
        categories.append("その他")
    return categories

分類時の注意:

  • str.lower() で英字を統一、日本語は原文のまま比較
  • 1回答が複数カテゴリに該当する場合は全て返す
  • 「なし」「特になし」系は専用リストで先に除外
  • 「その他」は末尾に配置

質的分析の CSV フォーマット

id,テーマ,引用,代表的
R001,テーマA,引用テキスト,1
R001,テーマB,引用テキスト,0
R002,テーマA,引用テキスト,0
  • id: 回答者ID(R001形式)
  • テーマ: 分類先テーマ名
  • 引用: 該当テキスト
  • 代表的: 代表的引用は 1、それ以外は 0

注意事項

  • Likert尺度の順序は必ずユーザーに確認する
  • 日本語ラベルは label_map から取得する
  • 自由記述の分類ルールはデータ固有(汎用ルールはない)
  • quarto render 前に uv sync で依存関係を最新にする

Sponsors

Details

Marketplace
ncukondo/agent-plugins
Source
plugins/quarto-survey-analysis
Category
Community

More from ncukondo/agent-plugins

All 2