
quarto-survey-analysis
Quarto アンケート分析 - CSVアンケートデータからQuarto+Pythonパイプラインで統計集計・可視化・PDFレポート・PPTXスライドを生成
Install
/plugin install quarto-survey-analysis@agent-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add ncukondo/agent-plugins.
Contents
Discovered from sourceSkills 2
Quarto アンケート分析プロジェクト環境構築
CSV アンケートデータを分析するための Quarto + Python プロジェクトをゼロから構築する。
目次
- 前提チェック
- ディレクトリ構成作成
- pyproject.toml 生成
- _quarto.yml 生成
- WSL検出・.mise.toml 生成
- .gitignore/.python-version 生成
- uv sync
- 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"
完了確認
以下をユーザーに報告する:
- 作成されたファイル一覧
uv syncの成否- 次のステップ:
data/に CSV を配置し、/survey-report-builderでレポート構築
注意事項
- Jupyter カーネルはカスタム名を使わず
python3に自動解決させる(ポータブル性のため) - WSL 環境では必ず venv をユーザーディレクトリに逃がす
uv run render/uv run previewがすぐ使えることを確認するoutput/ディレクトリは.gitignoreに含める
アンケート分析レポート構築
data/ に配置された CSV アンケートデータから、Quarto レポート(PDF)と発表用スライド(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— テーマ別集計
出力規約
ファイル命名
| 種類 | パス | 命名規則 |
|---|---|---|
| 度数分布 CSV | output/summary_{topic}.csv | 列名に対応 |
| クロス集計 CSV | output/summary_{topic}_cross.csv | 行列列名を結合 |
| 横棒グラフ SVG | output/figures/{topic}.svg | 列名に対応 |
| テーブル SVG | output/tables/{topic}.svg | テーブル名に対応 |
| ID付き全回答 | output/responses_with_id.csv | 固定名 |
| 自由記述抜粋 | output/free_text.csv | 固定名 |
| PPTX | output/{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