aipoch/arrive-guideline-architect

ARRIVE Guideline Architect

Overview

AI-powered protocol design tool that creates publication-ready animal research protocols compliant with ARRIVE 2.0 guidelines (Animal Research: Reporting of In Vivo Experiments). Generates structured documentation for ethical review, transparent reporting, and reproducible science.

Key Capabilities:

• Protocol Generation: Complete ARRIVE 2.0 compliant study protocols
• Sample Size Calculator: Statistical power analysis with justification
• Compliance Checker: Validate existing protocols against ARRIVE standards
• Randomization Schemes: Generate and document allocation strategies
• Ethics Support: IACUC protocol templates and animal welfare documentation
• Reporting Templates: Manuscript preparation with required elements

When to Use

✅ Use this skill when:

• Designing new animal studies requiring ethical approval
• Preparing IACUC (Institutional Animal Care and Use Committee) applications
• Writing manuscripts for journals requiring ARRIVE compliance (PLOS, Nature, etc.)
• Validating existing protocols for transparency and completeness
• Training researchers on animal research best practices
• Planning multi-site studies requiring standardized protocols
• Reviewing protocols for grant applications

❌ Do NOT use when:

• Human clinical trials → Use clinical-protocol-designer
• In vitro studies (cell culture only) → No ARRIVE requirements apply
• Field studies on wild animals → Use specialized wildlife research guidelines
• Veterinary clinical cases → Use veterinary case report standards
• Systematic reviews/meta-analyses → Use PRISMA guidelines

Integration:

• Upstream: sample-size-power-calculator (statistical design)
• Downstream: iacuc-protocol-drafter (ethics submission), manuscript-prep-assistant (publication)

Core Capabilities

1. ARRIVE 2.0 Protocol Builder

Generate complete protocols covering all Essential 10 items:

from scripts.arrive_builder import ARRIVEBuilder

builder = ARRIVEBuilder()

# Generate full protocol
protocol = builder.generate_protocol(
    title="Efficacy of Compound X in Type 2 Diabetes Mouse Model",
    species="Mus musculus",
    strain="db/db",
    groups=[
        {"name": "Control", "n": 15, "treatment": "Vehicle"},
        {"name": "Low Dose", "n": 15, "treatment": "10 mg/kg"},
        {"name": "High Dose", "n": 15, "treatment": "50 mg/kg"}
    ],
    primary_endpoint="Fasting blood glucose reduction",
    duration_days=28
)

protocol.save("protocol.md")

Generates:

1. Study Design: Experimental groups, timelines, endpoints
2. Sample Size: Power calculations with justification
3. Inclusion/Exclusion: Animal selection criteria
4. Randomization: Allocation method (software/hardware)
5. Blinding: Who, when, how blinding implemented
6. Outcome Measures: Primary, secondary, exploratory endpoints
7. Statistical Methods: Analysis plan, software, significance level
8. Experimental Animals: Species, strain, sex, age, weight, source
9. Experimental Procedures: Detailed methods with timing
10. Results Reporting: Data presentation templates

2. Sample Size Calculator

Statistical power analysis with ARRIVE-compliant justification:

from scripts.sample_size import SampleSizeCalculator

calc = SampleSizeCalculator()

# Calculate with effect size
result = calc.calculate(
    test_type="two_sample_t_test",
    effect_size=0.8,  # Cohen's d
    alpha=0.05,
    power=0.80,
    expected_dropout=0.10  # 10% attrition
)

# Output: n=26 per group (total 78, accounting for 10% dropout)

Features:

• Effect Size Selection: Cohen's d, odds ratio, hazard ratio
• Multiple Comparisons: Bonferroni, FDR corrections
• Dropout Adjustment: Account for expected attrition
• Justification Text: Auto-generate sample size rationale
• Power Curves: Generate power calculations for various sample sizes

3. Compliance Validator

Check existing protocols against ARRIVE 2.0:

python scripts/validate.py --input my_protocol.md --format markdown

Output:

✅ Essential 10: 10/10 complete
⚠️  Recommended Set: 8/15 complete
   Missing: Data sharing statement, Conflict of interest

Detailed Report:
- Item 1 (Study Design): Complete
- Item 2 (Sample Size): Complete  
- Item 3 (Inclusion Criteria): Missing - add exclusion criteria
- ...

Validation Levels:

• Essential 10: Required for all publications
• Recommended Set: Required by top-tier journals
• Journal-Specific: Custom checks for specific publishers

4. Randomization & Blinding Generator

Create allocation schemes with documentation:

from scripts.randomization import RandomizationGenerator

gen = RandomizationGenerator()

# Generate allocation
allocation = gen.generate(
    n_animals=45,
    n_groups=3,
    method="block_randomization",  # or "simple", "stratified"
    block_size=6,
    seed=42  # For reproducibility
)

# Output allocation table
allocation.save("allocation_table.csv")
allocation.generate_blinding_key("blinding_key.xlsx")

Methods Supported:

• Simple randomization
• Block randomization (fixed/random block sizes)
• Stratified randomization (by sex, age, baseline)
• Covariate-adaptive minimization

Common Patterns

Pattern 1: Drug Efficacy Study

Template for therapeutic intervention studies:

{
  "study_type": "efficacy",
  "species": "Mus musculus",
  "model": "Disease model (e.g., db/db diabetic mice)",
  "intervention": "Test compound",
  "groups": [
    "Sham control",
    "Disease control (vehicle)",
    "Positive control (reference drug)",
    "Test compound (low dose)",
    "Test compound (high dose)"
  ],
  "primary_endpoint": "Disease biomarker",
  "secondary_endpoints": ["Safety markers", "Histopathology"],
  "sampling_timepoints": ["Baseline", "Week 2", "Week 4"]
}

Key Considerations:

• Include positive control for assay validation
• Multiple doses to establish dose-response
• Power calculation based on expected effect size
• Sample size accounts for disease variability

Pattern 2: Toxicology Study

Template for safety assessment:

{
  "study_type": "toxicology",
  "species": "Rat",
  "duration": "28-day repeat dose",
  "dose_levels": ["Vehicle", "Low", "Mid", "High", "Limit"],
  "endpoints": [
    "Clinical observations (daily)",
    "Body weight (twice weekly)",
    "Food consumption",
    "Clinical pathology (hematology, chemistry)",
    "Necropsy and organ weights",
    "Histopathology"
  ],
  "recovery_groups": true  # 14-day recovery period
}

Key Considerations:

• Dose selection based on MTD (maximum tolerated dose)
• Recovery groups for reversibility assessment
• Comprehensive clinical pathology panels
• Histopathology on all high-dose and control animals

Pattern 3: Behavioral Study

Template for neuroscience/behavioral research:

{
  "study_type": "behavioral",
  "species": "C57BL/6 mice",
  "tests": [
    "Open field (anxiety/locomotion)",
    "Elevated plus maze (anxiety)",
    "Novel object recognition (memory)",
    "Fear conditioning (learning)"
  ],
  "controls": [
    "Positive pharmacological control",
    "Negative control (vehicle)"
  ],
  "blinding": "Video analysis performed blinded",
  "randomization": "Latin square design for test order"
}

Key Considerations:

• Counterbalance test order (learning effects)
• Blind video analysis to prevent bias
• Standardized testing environment (lighting, noise)
• Experimenter training and reliability testing

Pattern 4: Surgical Model Study

Template for procedure-based research:

{
  "study_type": "surgical",
  "procedure": "Myocardial infarction (LAD ligation)",
  "species": "Sprague-Dawley rats",
  "sham_control": true,
  "perioperative_care": {
    "analgesia": "Buprenorphine SR",
    "antibiotics": "Enrofloxacin",
    "monitoring": "Temperature, respiration, pain scoring"
  },
  "outcome_measures": [
    "Survival rate",
    "Echocardiography",
    "Histological infarct size"
  ],
  "humane_endpoints": ["Severe distress", "Inability to ambulate"]
}

Key Considerations:

• Detailed surgical protocol with timing
• Comprehensive perioperative care
• Clear humane endpoints (refinement)
• Sham surgery controls for procedure effects
• Pain management per IACUC guidelines

Complete Workflow Example

From study concept to IACUC submission:

# Step 1: Create study brief
cat > study_brief.json << EOF
{
  "title": "Novel Compound X in Diabetic Nephropathy",
  "species": "Mouse",
  "strain": "db/db",
  "groups": 4,
  "primary_endpoint": "Albuminuria reduction",
  "duration_weeks": 12
}
EOF

# Step 2: Generate protocol
python scripts/main.py \
  --input study_brief.json \
  --output protocol.md \
  --include-checklist

# Step 3: Calculate sample size
python scripts/sample_size.py \
  --test t_test \
  --effect-size 0.8 \
  --alpha 0.05 \
  --power 0.80 \
  --dropout 0.10

# Step 4: Generate randomization
python scripts/randomize.py \
  --n-total 64 \
  --n-groups 4 \
  --method block \
  --output allocation.csv

# Step 5: Validate ARRIVE compliance
python scripts/validate.py \
  --input protocol.md \
  --format pdf \
  --output compliance_report.pdf

Output Files:

output/
├── protocol.md                    # Complete ARRIVE protocol
├── sample_size_justification.txt  # Statistical rationale
├── allocation.csv                 # Randomization table
├── blinding_key.xlsx             # Blinding documentation
├── compliance_report.pdf         # ARRIVE checklist
└├── iacuc_supplemental.pdf       # Ethics committee materials

Quality Checklist

Pre-Study:

• [ ] CRITICAL: IACUC approval obtained before starting
• [ ] Sample size adequately powered (≥80%)
• [ ] Randomization method documented and reproducible
• [ ] Blinding plan clear for all assessors
• [ ] Humane endpoints defined with clear criteria
• [ ] Inclusion/exclusion criteria prespecified

During Study:

• [ ] Randomization followed without deviations
• [ ] Blinding maintained (unblinding only for safety)
• [ ] All animals accounted for (CONSORT-style flow diagram)
• [ ] Adverse events documented and reported to IACUC
• [ ] Sample collection at predetermined timepoints

Reporting:

• [ ] All Essential 10 items addressed in manuscript
• [ ] CONSORT-style flow diagram for animal studies
• [ ] Raw data available (or sharing statement)
• [ ] Conflict of interest disclosed
• [ ] Funding sources acknowledged

Common Pitfalls

Design Issues:

• ❌ Inadequate controls → Cannot distinguish treatment from confounding effects

  • ✅ Always include appropriate controls (vehicle, positive, sham)

• ❌ Convenience sampling → Selection bias

  • ✅ Random allocation to treatment groups

• ❌ Unblinded assessment → Observer bias

  • ✅ Blinded outcome assessment whenever possible

Sample Size Issues:

• ❌ No power calculation → Underpowered study, false negatives

  • ✅ Calculate sample size a priori with justification

• ❌ Ignoring dropout → Final sample too small

  • ✅ Account for expected attrition (typically 10-20%)

Reporting Issues:

• ❌ Selective outcome reporting → Publication bias

  • ✅ Pre-register primary and secondary endpoints

• ❌ Missing animal numbers → Transparency concerns

  • ✅ Report n for every analysis

References

Available in references/ directory:

• arrive_2.0_guidelines.md - Official ARRIVE 2.0 checklist and explanations
• sample_size_guidelines.md - Statistical methods for animal studies
• species_specific_requirements.md - Mouse, rat, zebrafish considerations
• journal_compliance.md - Requirements by publisher (Nature, Science, Cell)
• statistical_methods.md - Analysis approaches for common designs
• iacuc_templates.md - Ethics committee application templates
• example_protocols.md - Published compliant protocols as examples

Scripts

Located in scripts/ directory:

• main.py - Protocol generation CLI
• arrive_builder.py - Core protocol builder
• sample_size.py - Power analysis calculator
• randomization.py - Allocation scheme generator
• validate.py - ARRIVE compliance checker
• checklist_generator.py - Interactive checklist tool
• export.py - Multi-format output (PDF, Word, Markdown)

Limitations

• Template-Based: Generates standard protocols; highly specialized studies may need customization
• No Statistical Analysis: Calculates sample size but does not perform analysis
• No Real-Time Monitoring: Protocol generation only; does not track actual experiments
• Species Coverage: Optimized for mice and rats; other species may need adaptation
• Regulatory Variation: IACUC requirements vary by institution; may need local customization

---

🐾 Remember: The 3Rs (Replacement, Reduction, Refinement) are ethical imperatives. This tool supports Reduction (optimal sample sizes) and Refinement (better experimental design), but consider Replacement alternatives (in vitro, in silico) whenever possible.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | --interactive | flag | - | Interactive mode: Run wizard with guided prompts (uses input() for user interaction). Recommended for first-time users or complex study designs. | | --input | str | Required | Input JSON file path (batch/automation mode) | | --output | str | "protocol.md" | Output file path | | --validate | str | Required | Validate existing protocol file | | --checklist | str | Required | Generate ARRIVE 2.0 checklist | | --format | str | "markdown" | Output format: markdown, pdf, or docx |

Usage Modes:

• Automation Mode (Recommended for CI/CD): Use --input with JSON configuration file
• Interactive Mode: Use --interactive for guided setup via prompts

Example - Automation Mode:

# Create JSON config
cat > study_config.json << 'EOF'
{
  "title": "Diabetes Drug Study",
  "species": "Mus musculus",
  "strain": "db/db",
  "groups": 4,
  "animals_per_group": 15
}
EOF

# Generate protocol
python scripts/main.py --input study_config.json --output protocol.md

Example - Interactive Mode:

# Launch interactive wizard
python scripts/main.py --interactive