anatomy-quiz-master

# Anatomy Quiz Master

## Overview

Comprehensive anatomy education tool that generates interactive quizzes covering gross anatomy, neuroanatomy, and clinical anatomy with adaptive difficulty and detailed explanations.

**Key Capabilities:**
- **Regional Quizzes**: Head/neck, thorax, abdomen, pelvis, limbs
- **Multiple Question Types**: Identification, function, clinical correlation
- **Adaptive Difficulty**: Basic, intermediate, advanced levels
- **Image Integration**: Label identification with anatomical images
- **Progress Tracking**: Performance analytics and weak area identification
- **Exam Mode**: Timed simulations for USMLE-style preparation

## When to Use

**✅ Use this skill when:**
- Medical students preparing for anatomy practical exams
- Self-assessment after anatomy lectures or dissections
- Identifying weak anatomical regions for focused study
- Creating practice questions for study groups
- Remediation for students who failed anatomy assessments
- Preparing for USMLE Step 1 anatomy questions
- Teaching assistants generating quiz materials for labs

**❌ Do NOT use when:**
- Primary learning resource for anatomy → Use textbooks/atlas first
- Substitute for cadaver lab attendance → Use for supplemental practice only
- Pathology or physiology questions → Use specialized skills for those topics
- Board exam registration or scheduling → Use official NBME resources

**Integration:**
- **Upstream**: `usmle-case-generator` (clinical context), `anki-card-creator` (flashcard export)
- **Downstream**: `study-limitations-drafter` (weakness analysis), `performance-tracker` (progress monitoring)

## Core Capabilities

### 1. Regional Anatomy Quizzes

Generate focused quizzes by body region:

```python
from scripts.quiz_generator import QuizGenerator

generator = QuizGenerator()

# Generate thorax quiz
quiz = generator.generate_quiz(
    region="thorax",
    topics=["heart", "lungs", "mediastinum", "thoracic_wall"],
    difficulty="intermediate",
    n_questions=20
)

# Export for LMS
quiz.export(format="json", filename="thorax_quiz.json")
```

**Supported Regions:**
| Region | Subtopics | Question Types |
|--------|-----------|----------------|
| **Head & Neck** | Skull, cranial nerves, triangles, viscera | Identification, pathways, clinical |
| **Thorax** | Heart, lungs, mediastinum, pleura | Relations, auscultation, imaging |
| **Abdomen** | GI tract, retroperitoneum, vessels | Peritoneal reflections, vascular supply |
| **Pelvis** | Organs, perineum, walls | Gender differences, clinical correlations |
| **Upper Limb** | Shoulder, arm, forearm, hand | Muscle actions, innervation, clinical |
| **Lower Limb** | Hip, thigh, leg, foot | Gait, compartments, clinical exams |
| **Back** | Vertebral column, spinal cord, muscles | Levels, landmarks, clinical |

### 2. Neuroanatomy Pathway Tracing

Specialized quizzes for neural pathways:

```python
# Neuroanatomy quiz
neuro_quiz = generator.generate_neuro_quiz(
    pathway_type="motor",  # or "sensory", "cranial_nerves", "reflexes"
    include_lesions=True,
    clinical_correlations=True
)
```

**Pathway Types:**
- **Motor Pathways**: Corticospinal, corticobulbar, basal ganglia circuits
- **Sensory Pathways**: Dorsal column, spinothalamic, trigeminal
- **Cranial Nerves**: All 12 nerves with nuclei and clinical tests
- **Reflex Arcs**: Deep tendon, superficial, visceral
- **Vascular**: Arterial supply, venous drainage, stroke syndromes

### 3. Clinical Correlation Questions

Integrate anatomy with clinical scenarios:

```python
clinical_quiz = generator.generate_clinical_quiz(
    region="abdomen",
    scenario_types=["surgery", "radiology", "physical_exam"],
    difficulty="advanced"
)
```

**Question Formats:**
```
Clinical Scenario:
"A 45-year-old male presents with epigastric pain radiating to the back. 
CT shows a mass in the lesser sac."

Question: "Which artery runs immediately posterior to the body of the 
pancreas and would be at risk during resection?"

A) Splenic artery
B) Superior mesenteric artery
C) Common hepatic artery
D) Left gastric artery

Correct: B) Superior mesenteric artery

Explanation: The SMA emerges from the aorta at L1 and passes posterior 
to the neck of the pancreas and anterior to the uncinate process...
```

### 4. Adaptive Learning System

Adjust difficulty based on performance:

```python
from scripts.adaptive import AdaptiveEngine

engine = AdaptiveEngine()

# Track student performance
student_progress = engine.track_performance(
    student_id="student_001",
    quiz_results=results,
    time_per_question=True
)

# Generate personalized quiz targeting weak areas
personalized = engine.generate_adaptive_quiz(
    student_progress=student_progress,
    focus_areas=["thorax_vessels", "cranial_nerves"],
    mastery_threshold=0.80
)
```

**Adaptive Features:**
- **Spaced Repetition**: Re-test incorrect topics at optimal intervals
- **Difficulty Scaling**: Increase level after 3 consecutive correct answers
- **Time Pressure**: Gradually reduce time limits for speed practice
- **Weakness Identification**: Track performance by anatomical structure

## Common Patterns

### Pattern 1: Pre-Exam Comprehensive Review

**Scenario**: Student preparing for anatomy practical exam in 2 weeks.

```bash
# Generate full-body comprehensive quiz
python scripts/main.py \
  --mode comprehensive \
  --regions all \
  --difficulty intermediate \
  --n-questions 100 \
  --timed \
  --output pre_practice_exam.json

# Focus on weak areas identified
python scripts/main.py \
  --mode adaptive \
  --focus abdomen,pelvis \
  --difficulty advanced \
  --n-questions 30 \
  --output weak_areas_review.json
```

**Study Schedule:**
- Week 1: Comprehensive quizzes (all regions)
- Week 2: Focus on <80% score regions
- 3 days before: Timed practice exam
- Day before: Light review of marked difficult questions

### Pattern 2: Lab Session Preparation

**Scenario**: Student preparing for cadaver lab on upper limb.

```python
# Pre-lab identification quiz
pre_lab = generator.generate_image_quiz(
    region="upper_limb",
    structure_types=["muscles", "vessels", "nerves"],
    label_type="pins",  # Pin identification format
    n_questions=15
)

# Clinical correlation for post-lab
post_lab_clinical = generator.generate_clinical_quiz(
    region="upper_limb",
    clinical_types=["fractures", "nerve_injuries", "vascular"]
)
```

**Lab Integration:**
- Pre-lab: 15-minute identification quiz
- During lab: Reference key landmarks
- Post-lab: Clinical correlation quiz linking anatomy to disease

### Pattern 3: USMLE Step 1 Preparation

**Scenario**: Medical student preparing for USMLE Step 1.

```bash
# USMLE-style clinical anatomy
python scripts/main.py \
  --mode usmle \
  --clinical-focus \
  --mix-basic-advanced 70:30 \
  --n-questions 40 \
  --timed-per-question 60 \
  --output usmle_anatomy_practice.json
```

**USMLE Features:**
- Clinical vignette format
- Image-based questions (radiology, pathology)
- Two-step reasoning (identify structure → clinical implication)
- Time pressure simulation (60-90 seconds per question)

### Pattern 4: Teaching Assistant Lab Quiz

**Scenario**: TA needs to generate weekly lab quizzes.

```python
# Weekly lab quiz
ta_quiz = generator.generate_ta_quiz(
    week_number=5,
    region="thorax",
    practical_stations=8,
    time_per_station=3,  # minutes
    include_prosection_images=True
)

# Auto-generate answer key
answer_key = ta_quiz.generate_answer_key(
    include_acceptable_variations=True,
    grading_rubric="partial_credit"
)
```

**TA Tools:**
- Station-based practical exam format
- Answer keys with acceptable variations
- Grading rubrics
- Performance statistics by question

## Complete Workflow Example

**Comprehensive anatomy study session:**

```bash
# Step 1: Diagnostic quiz to identify weak areas
python scripts/main.py \
  --mode diagnostic \
  --regions all \
  --n-questions 50 \
  --output diagnostic_results.json

# Step 2: Generate focused study plan
python scripts/main.py \
  --analyze-results diagnostic_results.json \
  --generate-study-plan \
  --days 14 \
  --output study_plan.md

# Step 3: Daily quizzes following plan
python scripts/main.py \
  --mode daily \
  --study-plan study_plan.md \
  --day 1 \
  --output day1_quiz.json

# Step 4: Spaced repetition review
python scripts/main.py \
  --mode spaced-repetition \
  --incorrect-questions diagnostic_results.json \
  --interval 3_days \
  --output review_quiz.json

# Step 5: Final practice exam
python scripts/main.py \
  --mode exam \
  --regions all \
  --n-questions 100 \
  --timed 120_minutes \
  --output final_practice_exam.json
```

**Python API:**

```python
from scripts.quiz_generator import QuizGenerator
from scripts.progress_tracker import ProgressTracker
from reports.performance_report import PerformanceReport

# Initialize
generator = QuizGenerator()
tracker = ProgressTracker()

# Generate adaptive quiz
quiz = generator.generate_adaptive_quiz(
    student_id="med_student_001",
    target_regions=["abdomen", "pelvis"],
    difficulty_start="intermediate"
)

# Student takes quiz
results = quiz.administer()

# Track progress
tracker.record_results(
    student_id="med_student_001",
    quiz_id=quiz.id,
    results=results
)

# Generate progress report
report = PerformanceReport(
    student_id="med_student_001",
    time_range="last_30_days"
)
report.generate_pdf("anatomy_progress.pdf")

# Identify weak areas for next study session
weak_areas = tracker.identify_weak_areas(
    student_id="med_student_001",
    threshold=0.70
)
print(f"Focus next session on: {weak_areas}")
```

## Quality Checklist

**Question Quality:**
- [ ] Anatomical accuracy verified against standard atlases (Netter, Gray's)
- [ ] Clinical correlations reviewed by licensed physicians
- [ ] Multiple difficulty levels appropriately calibrated
- [ ] Distractors (wrong answers) are plausible and educational
- [ ] Explications explain *why* correct answer is right
- [ ] Image quality sufficient for identification (resolution, labeling)

**Educational Value:**
- [ ] Questions test high-yield anatomy (clinically relevant)
- [ ] Progressive difficulty builds knowledge systematically
- [ ] Clinical scenarios reflect real patient presentations
- [ ] Explanations include anatomical reasoning

**Technical Quality:**
- [ ] Randomization prevents pattern recognition
- [ ] No duplicate questions in quiz banks
- [ ] Image files properly licensed or original
- [ ] Accessibility compliance (alt text for images)

**Before Use:**
- [ ] **CRITICAL**: Faculty review for anatomical accuracy
- [ ] Pilot test with target student population
- [ ] Time limits appropriate for difficulty
- [ ] Answer key double-checked for errors

## Common Pitfalls

**Content Issues:**
- ❌ **Outdated anatomical knowledge** → Teaching old terminology
  - ✅ Use current Terminologia Anatomica standards

- ❌ **Nit-picky details** → Testing obscure structures rarely clinically relevant
  - ✅ Focus on high-yield anatomy that appears in clinical practice

- ❌ **Unclear images** → Poor resolution or confusing labels
  - ✅ Use high-quality images; test label legibility at screen resolution

**Educational Issues:**
- ❌ **Questions too easy** → No learning benefit
  - ✅ Calibrate to student level; aim for 60-80% success rate

- ❌ **No clinical context** → Pure memorization without application
  - ✅ Include clinical correlation questions

- ❌ **Punitive difficulty** → Discouraging rather than challenging
  - ✅ Provide encouraging feedback; focus on improvement

**Technical Issues:**
- ❌ **Predictable patterns** → Students game the system
  - ✅ Randomize question order and distractor placement

- ❌ **No progress tracking** → Can't identify weak areas
  - ✅ Implement analytics to guide focused study

## References

Available in `references/` directory:

- `netter_atlas_correlation.md` - Question-to-atlas page mapping
- `terminologia_anatomica.md` - Standard anatomical terminology
- `usmle_content_outline.md` - NBME anatomy topic frequencies
- `clinical_correlations.md` - High-yield clinical anatomy scenarios
- `image_sources.md` - Licensed anatomical image repositories
- `difficulty_calibration.md` - Bloom's taxonomy level alignment

## Scripts

Located in `scripts/` directory:

- `main.py` - CLI for quiz generation
- `quiz_generator.py` - Core question generation engine
- `neuro_quiz.py` - Specialized neuroanatomy questions
- `clinical_correlator.py` - Clinical scenario integration
- `adaptive_engine.py` - Personalized difficulty adjustment
- `image_quiz.py` - Label identification with images
- `progress_tracker.py` - Performance analytics
- `report_generator.py` - Progress reports and statistics

## Limitations

- **Cadaver Images**: Cannot replace hands-on dissection experience
- **3D Spatial Relations**: 2D images may not convey depth relationships
- **Variability**: Normal anatomical variation not fully captured
- **Updates**: Anatomical knowledge evolves; requires periodic review
- **Cultural Sensitivity**: Some anatomical terms may vary by region
- **Disability Accommodation**: Image-based questions need alternatives for visually impaired students

## Parameters

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| `--region`, `-r` | string | upper_limb | No | Anatomical region (upper_limb, lower_limb, thorax, abdomen, pelvis, head_neck, neuroanatomy) |
| `--difficulty`, `-d` | string | intermediate | No | Difficulty level (basic, intermediate, advanced) |
| `--count`, `-c` | int | 1 | No | Number of questions to generate |
| `--output`, `-o` | string | - | No | Output file path (JSON format) |
| `--format` | string | json | No | Output format (json or text) |
| `--list-regions` | flag | - | No | List all available regions and exit |

## Usage

### Basic Usage

```bash
# Generate single question
python scripts/main.py --region upper_limb

# Generate 10-question quiz
python scripts/main.py --region neuroanatomy --difficulty advanced --count 10 --output quiz.json

# List available regions
python scripts/main.py --list-regions

# Text format output
python scripts/main.py --region thorax --format text
```

## Risk Assessment

| Risk Indicator | Assessment | Level |
|----------------|------------|-------|
| Code Execution | Python script executed locally | Low |
| Network Access | No external API calls | Low |
| File System Access | Read/Write to specified output files only | Low |
| Instruction Tampering | Standard prompt guidelines | Low |
| Data Exposure | Output saved only to specified location | Low |

## Security Checklist

- [x] No hardcoded credentials or API keys
- [x] No unauthorized file system access (../)
- [x] Output does not expose sensitive information
- [x] Prompt injection protections in place
- [x] Input validation for all parameters
- [x] Output directory restricted to workspace
- [x] Script execution in sandboxed environment
- [x] Error messages sanitized

## Prerequisites

```bash
# Python 3.7+
# No additional packages required (uses standard library)
```

## Evaluation Criteria

### Success Metrics
- [x] Successfully generates quiz questions
- [x] Supports multiple anatomical regions
- [x] Provides correct answers with explanations
- [x] Handles edge cases (invalid regions, etc.)

### Test Cases
1. **Basic Functionality**: Generate single question → Returns valid question with options
2. **Edge Case**: Invalid region → Graceful error message
3. **Multiple Questions**: Generate 10 questions → Returns array of questions

## Lifecycle Status

- **Current Stage**: Draft
- **Next Review Date**: 2026-03-06
- **Known Issues**: None
- **Planned Improvements**:
  - Add image support for visual identification
  - Expand question bank
  - Add performance analytics

---

**🧠 Learning Tip: Anatomy is best learned through repeated exposure in multiple contexts. Use these quizzes to reinforce cadaver lab learning, not replace it. Focus on understanding relationships and clinical significance, not just memorization.**