QMellowQとは？

MellowQは、認知診断モデル（CDM）のQ行列設計を支援するWebツールです。テスト項目と認知スキル（アトリビュート）の対応関係を示すQ行列を、AIの力を借りながら効率的に作成できます。

Q行列（Q-matrix）とは？

Q行列は、各テスト項目がどの認知スキルを必要とするかを 0 / 1 で表した表です。CDMの分析に必須の要素で、設計の質が診断結果の精度に直結します。

項目	A1: 要点抽出	A2: 局所情報	A3: 意図理解
item_01	✅ 1	0	0
item_02	0	✅ 1	✅ 1
item_03	✅ 1	0	✅ 1

1 = そのスキルが正答に必要、0 = 不要

MellowQでできること

📄 PDF/Wordから項目を自動抽出
🤖 AIがアトリビュートを提案
📊 AIがQ行列候補を自動生成
✏️ チェックボックスで直接編集
📥 CSVで一括データ入力
📤 CSV・Rスクリプトをエクスポート
💾 プロジェクトを保存・再開
🌐 日本語・英語の両言語対応

QWhat is MellowQ?

MellowQ is a web-based tool for designing Q-matrices for Cognitive Diagnostic Models (CDMs). It helps researchers efficiently create Q-matrices — the mapping between test items and cognitive skills — with AI assistance.

What is a Q-matrix?

A Q-matrix is a table that specifies which cognitive skills (attributes) each test item requires, coded as 0 or 1. It is a required input for CDM analysis, and its quality directly affects diagnostic accuracy.

Item	A1: Main Idea	A2: Local Detail	A3: Speaker Intent
item_01	✅ 1	0	0
item_02	0	✅ 1	✅ 1
item_03	✅ 1	0	✅ 1

1 = skill required for correct response, 0 = not required

What MellowQ can do

📄 Auto-extract items from PDF/Word
🤖 AI-suggested attributes
📊 AI-generated Q-matrix candidates
✏️ Direct editing via checkboxes
📥 Bulk data input via CSV
📤 Export to CSV + R script
💾 Save and resume projects
🌐 Japanese / English bilingual

→全体の流れ

MellowQは以下の5ステップで使います。AIアシスト機能を使って効率化できます。

→Workflow Overview

MellowQ follows a 5-step process. You can use AI assistance to speed up each step.

AI

AIアシスト
（準備）

AI Assist
(Prep)

1

アトリビュート
定義

Define
Attributes

2

項目
入力

Enter
Items

3

AI候補
生成

AI
Candidates

4

Q行列
編集

Edit
Q-Matrix

5

エクスポート
・分析

Export
& Analyze

はじめての方へ「デモを読み込む」ボタンを押すと、サンプルデータで全機能を体験できます。実際のデータを使う前に、まずデモで流れをつかんでください。

おすすめの進め方ステップ①②でデータを準備してから③でAI生成 → ④で精査・修正 → ⑤でエクスポートの順が最も効率的です。項目数が多い場合は、PDFアップロードで②を大幅に省力化できます。

First time? Click "Load Demo" to explore all features with sample data before using your own test.

Recommended approach: Prepare data in steps ① and ②, generate AI candidates in ③, review and refine in ④, then export in ⑤. For large item sets, use PDF upload to automate step ②.

AIAIアシスト — 準備を効率化する

画面上部の「AIアシスト」カードには、作業を大幅に省力化する2つの機能があります。

PDF / Word から項目を自動抽出

テスト冊子のPDFまたはWordファイルをドロップするだけで、Gemini AIが項目文・選択肢・正答を自動的に抽出し「② 項目入力」欄に追加します。

PDFまたは .docx ファイルをドロップゾーンにドラッグ＆ドロップ（またはクリックして選択）
AIがテキストを解析し、項目として追加
抽出後に「出題意図」欄を手入力するとAI提案の精度が上がります

注意スキャンPDF（画像PDF）はテキスト抽出できません。OCR処理済みのPDF、またはWordファイルをご使用ください。

AIにアトリビュートを提案させる

テストの概要と項目を入力した後、「AIにアトリビュートを提案させる」ボタンを押すと、そのテストに適した認知スキル（アトリビュート）の候補を4〜8個提案します。

「テスト概要」欄にテストの目的・対象・測定スキルを入力（任意だが精度向上に有効）
項目を少なくとも1つ読み込んでからボタンを押す
提案された各アトリビュートを確認し「採用」ボタンまたは「全て採用」で追加
採用後、ラベル・説明・キーワードを必要に応じて修正する

ポイントAIの提案はあくまで「たたき台」です。テスト設計の理論・先行研究に基づき、専門家として最終判断してください。

AIAI Assist — Streamline Your Preparation

The "AI Assist" card at the top of the page offers two features that significantly reduce manual work.

Auto-extract items from PDF / Word

Drop a test booklet PDF or Word file onto the drop zone and Gemini AI will automatically extract stems, options, and answers, adding them to "② Item Input".

Drag and drop a PDF or .docx file onto the drop zone (or click to select)
AI analyzes the text and adds items automatically
Manually fill in "Item Intent" after extraction to improve AI suggestions

NoteScanned PDFs (image-only) cannot be processed. Use OCR-processed PDFs or Word files.

Have AI suggest attributes

After loading items, click "Have AI suggest attributes" to receive 4–8 cognitive skill attribute candidates appropriate for your test.

Enter test overview (optional but improves accuracy)
Load at least one item before clicking the button
Review each candidate and click "Adopt" or "Adopt All"
Edit labels, descriptions, and keywords as needed

Key pointAI suggestions are starting points only. As a subject-matter expert, make the final decisions based on your test design theory and prior research.

1アトリビュート定義

アトリビュートとは、テスト項目に正答するために必要な認知スキルのことです。CDMの分析結果は、アトリビュートの定義の質に大きく依存します。

アトリビュートの設計指針

✅ 独立性 — 各アトリビュートは互いに独立した認知プロセスを表すこと
✅ 観察可能性 — テスト項目で測定・識別できるスキルであること
✅ 適切な粒度 — 細かすぎず（1項目1スキル）、粗すぎず（全項目同スキル）
✅ 数 — 通常3〜8個。多すぎると推定精度が下がる
❌ 避けるべき — 「難しさ」「長さ」など項目特性そのものをアトリビュートにしない

入力方法

方法	手順	適した場面
手動追加	「アトリビュート追加」ボタンを押して1件ずつ入力	アトリビュートが少ない・精緻に設計したい
AI提案	AIアシストカードで提案を採用	初期案のたたき台が欲しい
CSV一括	「アトリビュート一括追加」でCSVファイルをアップロード	既存データがある・複数人で分担

各フィールドの説明

フィールド	説明	例
`ID`	自動採番（A1, A2…）。変更可能。重複不可	A1
`ラベル`	スキルの短い名前（5〜8文字推奨）	要点抽出
`説明`	スキルの定義。Q行列作成の基準として使用	話全体の主旨をつかむ
`キーワード`	AIがQ行列候補を生成する際に使用。カンマ区切り	要点,主旨,summary,gist

キーワードのコツ日本語と英語の両方を入れると、英語の項目文にも対応できます。項目文中によく出る語を含めると精度が上がります。

1Attribute Definition

Attributes are the cognitive skills required to answer test items correctly. The quality of CDM diagnostic results heavily depends on how well attributes are defined.

Attribute Design Principles

✅ Independence — Each attribute should represent a distinct cognitive process
✅ Observability — Attributes must be measurable through test items
✅ Appropriate granularity — Not too narrow (1 item = 1 skill) or too broad (all items = 1 skill)
✅ Number — Typically 3–8 attributes; too many reduces estimation accuracy
❌ Avoid — Item properties like "difficulty" or "length" should not be attributes

Input Methods

Method	Steps	Best for
Manual	Click "Add Attribute" to enter one at a time	Few attributes, precise design
AI Suggest	Adopt from AI Assist card	Need a starting point
CSV Bulk	Click "Bulk Add Attributes" and upload a CSV	Existing data, team collaboration

Field Descriptions

Field	Description	Example
`ID`	Auto-numbered (A1, A2…). Editable. Must be unique	A1
`Label`	Short name for the skill (2–5 words)	Main Idea Extraction
`Description`	Definition of the skill. Used as the Q-matrix design criterion	Identify the overall gist of the passage
`Keywords`	Used by AI when generating Q-matrix candidates. Comma-separated	main idea,gist,summary,overall

Keyword tipIncluding both Japanese and English keywords helps when item stems are in either language. Use terms that frequently appear in your items.

2項目入力

分析対象のテスト項目を入力します。AIのQ行列候補生成の精度を高めるために、「出題意図」フィールドを活用してください。

入力方法

方法	手順
手動追加	「項目追加」ボタンで1件ずつ入力
PDF/DOCX	AIアシストのドロップゾーンにファイルをドロップ（自動抽出）
CSV一括	「項目一括追加」でCSVファイルをアップロード

各フィールドの説明

フィールド	説明	重要度
`項目ID`	一意のID。自動採番（item_01…）	必須
`項目文`	設問の本文	必須
`選択肢`	A. … B. … の形式で改行区切り	推奨
`正答`	正解の選択肢記号（A, B, C, D など）	推奨
`出題意図`	この項目で測定したいスキルの説明。AI精度向上に最も有効	重要
`メモ`	スクリプト・ルーブリックなど自由記述	任意

出題意図を書くと大きく改善「出題意図」欄に「話者の主旨を推論する能力を測る」などと書いておくだけで、AIのQ行列候補の精度が格段に上がります。アトリビュート提案にも活用されます。

2Item Input

Enter the test items to be analyzed. Use the "Item Intent" field to significantly improve AI Q-matrix candidate quality.

Input Methods

Method	Steps
Manual	Click "Add Item" to enter one at a time
PDF/DOCX	Drop a file onto the AI Assist drop zone (auto-extracted)
CSV Bulk	Click "Bulk Add Items" and upload a CSV

Field Descriptions

Field	Description	Priority
`Item ID`	Unique identifier. Auto-numbered (item_01…)	Required
`Stem`	The question text	Required
`Options`	A. … B. … format, one per line	Recommended
`Answer`	Correct option letter (A, B, C, D…)	Recommended
`Item Intent`	Description of the skill being measured. Most impactful for AI accuracy	Important
`Notes`	Scripts, rubrics, free notes	Optional

Item Intent dramatically improves resultsSimply writing "Tests the ability to infer the speaker's main argument" in the Intent field significantly improves AI Q-matrix candidate accuracy and attribute suggestions.

3AI候補と理由

アトリビュートと項目が揃ったら、AIにQ行列の候補を生成させます。AIが各項目に必要なスキルを分析し、主候補・副候補・自信度・根拠を提示します。

使い方

「AIでQ行列候補を生成」ボタンを押す（Gemini APIが動作）
各項目カードに主候補（緑タグ）と副候補（青タグ）が表示される
「理由」を読んでAIの判断根拠を確認する
内容に納得したら「→ Q行列に反映」ボタンを押す
ステップ④のQ行列が自動更新され、対象行が緑にフラッシュする

自信度の見方

自信度	意味	対応
高	項目文・意図とアトリビュートが明確に対応	そのまま反映してよい場合が多い
中	対応はあるが解釈の余地がある	根拠を読んで判断
低	キーワード一致が弱い、または曖昧	専門家判断で手修正を推奨

AI候補はあくまで補助ツールAIは項目文とキーワードを照合して提案します。テスト設計の専門的知見に基づく最終判断は必ず人間が行ってください。自信度「低」の項目は特に慎重に確認してください。

アトリビュート・項目を変更したら再生成アトリビュートや項目を追加・編集した場合、候補が古くなります。警告バナーが表示されたら再度「生成」ボタンを押してください。

3AI Candidates & Rationale

Once attributes and items are ready, have AI generate Q-matrix candidates. AI analyzes which skills each item requires and provides primary candidates, secondary candidates, confidence levels, and rationale.

How to use

Click "Generate AI Q-Matrix Candidates" (calls the Gemini API)
Each item card shows primary candidates (green tags) and secondary candidates (blue tags)
Read the "Rationale" to understand AI's reasoning
Click "→ Apply to Q-Matrix" when satisfied
The Q-matrix in step ④ updates automatically with a green flash on the updated row

Understanding Confidence Levels

Confidence	Meaning	Action
High	Clear match between item and attribute	Usually safe to apply directly
Medium	Plausible but open to interpretation	Read rationale before deciding
Low	Weak keyword match or ambiguous	Expert review and manual adjustment strongly recommended

AI candidates are a tool, not the final answerAI matches item text against keywords. All final Q-matrix decisions must be made by a domain expert. Always review Low-confidence items carefully.

Regenerate after changesIf you add or edit attributes or items after generating candidates, the candidates become stale. Click the button again when you see the warning banner.

4Q行列編集

AI候補を反映した後、専門家の視点でQ行列を精査・修正します。

操作方法

緑のセル（チェック済み）= 1（そのスキルが必要）、白のセル = 0
チェックボックスをクリックするだけで0/1を切り替えられる
右上の「密度」表示で行列全体のバランスを確認（通常20〜60%程度が目安）

Q行列の品質チェック

✅ すべてのアトリビュートが最低2〜3項目で測定されているか？
✅ すべての項目が最低1つのアトリビュートを持っているか？
✅ 単独アトリビュート（1つだけ必要）の項目と複合項目がバランスよく混在しているか？
✅ 専門的知見に照らして各セルの0/1が妥当か？

識別性の確保同じQ行列行（同じアトリビュートパタン）を持つ項目が多すぎると、アトリビュートの識別精度が下がります。できるだけ多様なパタンを含むよう設計してください。

4Q-Matrix Editor

After applying AI candidates, review and refine the Q-matrix using your domain expertise.

How to Edit

Green cells (checked) = 1 (skill required), white cells = 0
Click any checkbox to toggle 0/1
Check the "density" display (top right) to monitor overall balance (typically 20–60%)

Q-Matrix Quality Checklist

✅ Is every attribute measured by at least 2–3 items?
✅ Does every item require at least one attribute?
✅ Is there a balanced mix of single-attribute and multi-attribute items?
✅ Is each 0/1 entry justified by your domain expertise?

Ensuring identifiabilityIf too many items share the same Q-matrix row (same attribute pattern), attribute estimation accuracy decreases. Design for diverse patterns across items.

5エクスポート

完成したQ行列と関連データをダウンロードします。画面最下部の「エクスポート」セクションから行います。

ダウンロードできるファイル

ファイル	内容	主な用途
`q_matrix.csv`	Q行列本体。行=項目, 列=アトリビュート	Rへの入力
`responses_template.csv`	回答データの雛形（item_id列付き）	Rへの入力
`gdina_analysis.R`	GDINAパッケージを使ったR分析スクリプト	R分析
`attributes.csv`	アトリビュート定義一覧	記録・共有
`items_master.csv`	全項目のメタデータ	記録・共有
`project.json`	プロジェクト全体の保存ファイル	作業再開

文字コードについてすべてのCSVはUTF-8 BOM付きで出力されます。Excelで直接開いても日本語が文字化けしません。RのCSV読み込み時もBOMは自動的に無視されます。

5Export

Download the completed Q-matrix and related data from the "Export" section at the bottom of the page.

Available Files

File	Contents	Use
`q_matrix.csv`	Q-matrix. Rows = items, columns = attributes	R input
`responses_template.csv`	Response data template (with item_id column)	R input
`gdina_analysis.R`	R analysis script using the GDINA package	R analysis
`attributes.csv`	Attribute definition list	Record/Share
`items_master.csv`	Item metadata	Record/Share
`project.json`	Full project save file	Resume work

Character encodingAll CSVs are exported with UTF-8 BOM, so they open correctly in Excel without encoding issues. R's read.csv() ignores the BOM automatically.

RRでの分析

エクスポートしたファイルをRで分析する手順です。

準備

同じフォルダに q_matrix.csv、gdina_analysis.R を置く
responses_template.csv を元に実際の回答データ responses.csv を作成する（1列目: 受験者ID、2列目以降: 各項目の正誤 0/1）
Rで以下を実行してパッケージをインストール（初回のみ）

install.packages("GDINA")

分析スクリプトの実行

source("gdina_analysis.R")

スクリプトは以下の順で処理を実行します：

データの読み込みと確認
G-DINA モデルの推定（mono.constraint = TRUE）
Q行列の妥当性検証（Wald検定・Mesa プロット）
モデル適合度の評価（AIC・BIC・RMSEA など）
項目ごとのモデル選択
項目パラメタと識別力指標の出力
分類精度（EAP/MAP）の評価
個人のアトリビュート習得パタン推定・CSV保存

responses.csv の作成responses_template.csv を Excel や Numbers で開き、1行目のヘッダーを保ったまま2行目以降に回答データを入力してください。各セルは 0（誤答）または 1（正答）です。

RR Analysis

Steps for analyzing exported files in R.

Setup

Place q_matrix.csv and gdina_analysis.R in the same folder
Create responses.csv from responses_template.csv: column 1 = respondent ID, columns 2+ = item responses (0 = incorrect, 1 = correct)
Install the required package in R (first time only)

install.packages("GDINA")

Running the Analysis Script

source("gdina_analysis.R")

The script runs the following steps:

Load and verify data
G-DINA model estimation (mono.constraint = TRUE)
Q-matrix validation (Wald test, Mesa plots)
Model-data fit evaluation (AIC, BIC, RMSEA, etc.)
Item-level model selection
Item parameters and discrimination indices
Classification accuracy (EAP/MAP)
Individual attribute mastery pattern estimation + CSV export

Creating responses.csvOpen responses_template.csv in Excel or any spreadsheet app. Keep row 1 as the header and enter response data from row 2 onwards. Each cell = 0 (incorrect) or 1 (correct).

CSVフォーマット

一括追加用CSVの列構成

「テンプレートCSV」ボタンでサンプルファイルをダウンロードできます。

attributes_template.csv

列名	説明	必須
`attribute_id`	ユニークなID（例: A1）	必須
`label`	ラベル	必須
`description`	説明	任意
`keywords`	キーワード（カンマ区切り）	任意

items_template.csv

列名	説明	必須
`item_id`	ユニークなID（例: item_01）	必須
`stem`	項目文	必須
`options`	選択肢（改行区切り）	任意
`answer`	正答	任意
`intent`	出題意図	任意
`notes`	メモ	任意

1行目はヘッダー行です（変更しないでください）。2行目以降にデータを入力します。IDが既存のものと重複した場合は自動的にリネームされます。

CSV Format

CSV Column Structure for Bulk Upload

Download sample files using the "Template CSV" button in the app.

attributes_template.csv

Column	Description	Required
`attribute_id`	Unique ID (e.g. A1)	Required
`label`	Attribute label	Required
`description`	Description	Optional
`keywords`	Keywords (comma-separated)	Optional

items_template.csv

Column	Description	Required
`item_id`	Unique ID (e.g. item_01)	Required
`stem`	Item stem text	Required
`options`	Answer options (one per line)	Optional
`answer`	Correct answer	Optional
`intent`	Item intent	Optional
`notes`	Notes	Optional

Row 1 is always the header row — do not change it. Enter data from row 2 onwards. Duplicate IDs are automatically renamed.

よくある質問

アトリビュートは何個が適切ですか？

一般的に3〜8個が推奨されます。少なすぎると診断の粒度が粗くなり、多すぎると推定に必要なサンプルサイズが増大し精度が下がります。CDMの文献では「属性数 × 項目数」のバランスも重要とされており、各アトリビュートに最低3〜4項目が対応するよう設計してください。

AIの提案と専門家の判断が食い違った場合はどうしますか？

必ず専門家判断を優先してください。AIは項目文とキーワードの照合に基づく提案であり、テスト設計の理論的背景や認知過程の専門知識は持っていません。AIの提案は「気づきのきっかけ」として活用し、最終判断は常に人間が行ってください。

作業途中で保存することはできますか？

はい、二つの方法があります。①ブラウザのlocalStorageに自動保存されるため、同じブラウザを使う限り次回も作業を継続できます。②「エクスポート」セクションの「project.json」ボタンで明示的にファイル保存でき、別のコンピュータや別のブラウザでも再開できます。

CSVファイルをExcelで開いたら文字化けしました

MellowQのCSVはUTF-8 BOM付きで出力されます。通常のExcel（Windows）では正しく開けるはずです。もし文字化けする場合は、ExcelのデータタブからCSVをインポートし、エンコードに「UTF-8」を指定してください。

AIが動作しません

サーバーのconfig.phpにGemini APIキーが正しく設定されているか確認してください。APIキーが未設定の場合、ヒューリスティック（キーワード照合）モードで動作します。また、インターネット接続が必要です。

ヒューリスティックモードとは何ですか？

Gemini APIが利用できない場合（APIキー未設定・接続エラーなど）に自動的に切り替わるフォールバックモードです。アトリビュートのキーワードと項目文を照合してQ行列候補を生成します。AIよりも精度は劣りますが、オフラインでも基本的な候補生成が可能です。

Frequently Asked Questions

How many attributes should I use?

Generally 3–8 attributes are recommended. Too few limits diagnostic granularity; too many increases the required sample size and reduces estimation accuracy. CDM literature also emphasizes balance: aim for at least 3–4 items per attribute.

What if AI suggestions conflict with my expert judgment?

Always prioritize expert judgment. AI suggestions are based on keyword matching only — they lack the theoretical background and cognitive process expertise you bring. Use AI as a starting point and idea generator, but make all final decisions yourself.

Can I save my work in progress?

Yes, in two ways. ① The app auto-saves to your browser's localStorage, so the same browser will restore your work next time. ② Use the "project.json" button in the Export section to save a file you can use on any computer or browser.

CSV files show garbled text when opened in Excel

MellowQ exports UTF-8 BOM CSVs, which normally open correctly in Excel. If you still see garbled text, import the CSV via Excel's Data tab and set encoding to "UTF-8".

AI is not working

Check that the Gemini API key is correctly set in config.php on the server. Without a valid key, the app falls back to heuristic mode. An active internet connection is required for AI features.

What is heuristic mode?

A fallback mode that activates when the Gemini API is unavailable (no key, connection error, etc.). It matches attribute keywords against item text to generate Q-matrix candidates. Less accurate than AI but works without internet access.

ヒントとベストプラクティス

Q行列設計の黄金律

「AIが提案し、専門家が判断し、データが検証する」— AIの提案をたたき台として、理論的背景・先行研究・認知過程の専門知識に基づいて修正し、最終的にRの統計的妥当化（Qval関数・Mesa プロット）で確認するのが理想的なワークフローです。

作業効率化のコツ

📄 PDFアップロードから始める — 項目入力の手間を大幅に削減できます
✍️ 出題意図を先に書く — AIの精度が最も上がる投資対効果の高い作業です
🔤 キーワードは日英両方 — 英語の項目文にも対応できるようになります
💾 こまめにproject.jsonを保存 — 万が一のブラウザクラッシュに備えて
👥 複数人でのレビュー — Q行列はCSVでエクスポートして共有・議論できます

よくある失敗と対処法

問題	原因	対処
AIの提案が的外れ	キーワードが不足・出題意図が未入力	キーワードと出題意図を充実させてから再生成
密度が高すぎる（80%以上）	アトリビュートが多すぎ・設定が緩い	アトリビュートを統合・精査する
密度が低すぎる（10%未満）	アトリビュートが多すぎ・キーワードが不足	アトリビュートを減らすか定義を見直す
同じパタンの行が多い	項目の多様性が不足	Q行列の識別性を検討・項目を見直す

Tips & Best Practices

The Golden Rule of Q-Matrix Design

"AI proposes, the expert decides, data validates." Use AI suggestions as a starting point, refine them with your theoretical background and domain expertise, then confirm with statistical validation in R (Qval function, Mesa plots).

Efficiency Tips

📄 Start with PDF upload — Dramatically reduces item entry time
✍️ Write item intent first — Highest ROI activity for improving AI accuracy
🔤 Include bilingual keywords — Handles both Japanese and English item text
💾 Save project.json regularly — Protects against browser crashes
👥 Multi-expert review — Export CSV and share for discussion and consensus-building

Common Issues & Solutions

Issue	Likely Cause	Solution
AI suggestions off-target	Sparse keywords; missing item intent	Expand keywords and add item intent, then regenerate
Density too high (80%+)	Too many attributes or loose criteria	Merge or refine attributes
Density too low (under 10%)	Too many attributes or narrow keywords	Reduce attribute count or broaden definitions
Many identical row patterns	Insufficient item variety	Review item set for Q-matrix identifiability

📎 引用方法 / How to Cite

MellowQ を研究や授業で使用された場合は、以下の形式で引用してください。
If you use MellowQ in your research or teaching, please cite it as follows.

APA 7th Edition

Mizumoto, A. (2026, April 5). MellowQ [Web application]. Langtest.jp. https://langtest.jp/mellowq/

📌 Note Because the release date (April 5, 2026) is explicitly stated, n.d. is not needed. Please add the date you accessed the application as the retrieval date if required by your citation style.