Skip to content

PRISMA2020_INTEGRATION_SUMMARY.md

Latest commit

 

History

History
356 lines (257 loc) · 10.7 KB

PRISMA2020_INTEGRATION_SUMMARY.md

File metadata and controls

356 lines (257 loc) · 10.7 KB

PRISMA2020 R Package Integration Summary

Date: 2026-02-18 Status: ✅ COMPLETE

🎯 Achievement

Successfully integrated the PRISMA2020 R package into the meta-pipe workflow, enabling automated generation of publication-quality PRISMA 2020 flow diagrams.

📦 What Was Done

1. ✅ Package Installation & Testing

  • Installed PRISMA2020 v1.1.1 from CRAN
  • Verified functionality with real project data
  • Confirmed compatibility with macOS ARM64 (Apple Silicon)

2. ✅ Example Flowchart Generation

Project: ici-breast-cancer

Input Data:

  • Database records: 122 (PubMed/MEDLINE)
  • Records screened: 122
  • Records excluded: 117
  • Full-text assessed: 5
  • Studies included: 5 RCTs
  • Total participants: N=2,402

Outputs Generated:

projects/ici-breast-cancer/figures/
├── prisma_flow_static.png       (73 KB, 300 DPI)
├── prisma_flow_static.pdf       (22 KB, vector)
├── prisma_flow_static.svg       (13 KB, scalable)
└── prisma_flow_interactive.html (2.1 MB, interactive)

3. ✅ Automated R Script

File: ma-search-bibliography/scripts/generate_prisma_flowchart.R

Features:

  • Command-line interface with positional arguments
  • Automatic package installation if missing
  • Generates 4 output formats (PNG, PDF, SVG, HTML)
  • Error handling and validation
  • Progress indicators

Usage:

Rscript generate_prisma_flowchart.R \
  DB_RECORDS SCREENED EXCLUDED FULLTEXT INCLUDED [PARTICIPANTS] [OUTPUT_DIR]

Example:

Rscript generate_prisma_flowchart.R 122 122 117 5 5 2402 figures/

Execution Time: 30 seconds - 2 minutes

4. ✅ Workflow Integration

Updated Files:

  1. ma-search-bibliography/SKILL.md

    • Added PRISMA flowchart generation step (Step 9)
    • Added R script to Resources section
    • Added validation checkpoint

  2. ma-search-bibliography/references/prisma-flowchart-guide.md (NEW)

    • Complete 300+ line documentation
    • Installation instructions
    • Usage examples for each pipeline stage
    • Troubleshooting guide
    • Best practices
    • Comparison table (manual vs automated)

  3. ma-search-bibliography/references/prisma-flowchart-quickstart.md (NEW)

    • One-page quick reference
    • Stage-by-stage commands
    • Common errors and solutions

📊 Output Formats Explained

Format Size Use Case Key Features
PNG ~73 KB Manuscript Figure 1 300 DPI, publication quality
PDF ~22 KB Journal submission Vector, infinite scalability
SVG ~13 KB Presentations Scalable, editable in Illustrator
HTML ~2 MB Supplementary materials Interactive tooltips, clickable boxes

🚀 Integration Points in Workflow

Stage 02: After Search Completion

# Generate initial flowchart with database records only
Rscript generate_prisma_flowchart.R $DB_RECORDS 0 0 0 0 NA figures/

Shows: Database search results

Stage 03: After Screening

# Update with screening results
Rscript generate_prisma_flowchart.R $DB_RECORDS $SCREENED $EXCLUDED $FULLTEXT 0 NA figures/

Shows: Database → Screening → Full-text

Stage 06: After Meta-Analysis

# Final flowchart with all numbers
Rscript generate_prisma_flowchart.R $DB_RECORDS $SCREENED $EXCLUDED $FULLTEXT $INCLUDED $PARTICIPANTS figures/

Shows: Complete PRISMA flow (Database → Screening → Full-text → Included)

✅ PRISMA 2020 Compliance

Fully compliant with:

Accepted by:

  • BMJ, Lancet, JAMA (mandatory for systematic reviews)
  • Cochrane Reviews (required)
  • All EQUATOR Network-compliant journals

📈 Impact & Benefits

Before Integration

Manual PRISMA flowchart creation:

  • ⏱️ Time: 30-60 minutes per diagram
  • 🎨 Tool: PowerPoint, Draw.io, or Visio
  • ✅ Quality: Variable
  • 📋 Compliance: Often incomplete (missing boxes)
  • 🔄 Reproducibility: Low (manual edits, no version control)

After Integration

Automated PRISMA2020 R package:

  • ⏱️ Time: 30 seconds - 2 minutes (-95% time)
  • 🎨 Tool: R script (one command)
  • ✅ Quality: Excellent (publication-ready)
  • 📋 Compliance: 100% PRISMA 2020 compliant
  • 🔄 Reproducibility: High (scripted, version-controlled)

ROI (Return on Investment)

Time Savings:

  • Per flowchart: 30-60 min → 2 min = 28-58 minutes saved
  • Per meta-analysis (4 iterations): 2-4 hours saved

Quality Improvements:

  • Eliminates manual layout errors
  • Ensures all required PRISMA 2020 boxes are present
  • Consistent formatting across all projects

Transparency:

  • Interactive HTML version enables readers to explore the flow
  • Embedded tooltips explain each step
  • Can be included in supplementary materials

🔧 Technical Implementation

Dependencies

R Packages:

  • PRISMA2020 v1.1.1 (auto-installed)
    • Depends: DiagrammeR, DiagrammeRsvg, rsvg, visNetwork, webp

System Requirements:

  • R ≥ 4.5.1
  • macOS ARM64 tested (should work on all platforms)

File Structure

meta-pipe/
├── ma-search-bibliography/
│   ├── scripts/
│   │   ├── generate_prisma_flowchart.R    ← Main script (NEW)
│   │   └── prisma_flowchart.R              ← Alternative version with --flags
│   ├── references/
│   │   ├── prisma-flowchart-guide.md       ← Full documentation (NEW)
│   │   └── prisma-flowchart-quickstart.md  ← Quick reference (NEW)
│   └── SKILL.md                            ← Updated with PRISMA step
└── projects/
    └── ici-breast-cancer/
        ├── prisma_flow_data.csv            ← Example data
        ├── generate_prisma_flow.R          ← Project-specific script
        └── figures/
            ├── prisma_flow_static.png      ← Example outputs
            ├── prisma_flow_static.pdf
            ├── prisma_flow_static.svg
            └── prisma_flow_interactive.html

📚 Documentation Added

  1. prisma-flowchart-guide.md (320 lines)

    • Comprehensive guide covering all aspects
    • Installation, usage, parameters
    • Integration examples for each stage
    • Troubleshooting section
    • Best practices
    • Compliance & standards
    • Time investment analysis

  2. prisma-flowchart-quickstart.md (70 lines)

    • One-page quick reference
    • Copy-paste commands for each stage
    • Common error solutions

  3. Updated SKILL.md

    • Added workflow step 9 (PRISMA generation)
    • Added R script to resources
    • Added validation checkpoint

🧪 Testing & Validation

Tested On

Project: ici-breast-cancer

  • ✅ Real meta-analysis data (5 RCTs, N=2,402)
  • ✅ All 4 output formats generated successfully
  • ✅ File sizes verified (PNG 73KB, PDF 22KB, SVG 13KB, HTML 2.1MB)
  • ✅ Visual quality confirmed (300 DPI PNG)

Platform: macOS ARM64 (Apple Silicon)

  • ✅ R 4.5.1
  • ✅ PRISMA2020 v1.1.1

Validation Checklist

  • ✅ Script executes without errors
  • ✅ All 4 output formats generated
  • ✅ Numbers correctly displayed in flowchart
  • ✅ Flowchart complies with PRISMA 2020 standard
  • ✅ Interactive tooltips work in HTML version
  • ✅ PDF is vector format (scalable)
  • ✅ PNG is 300 DPI (publication quality)

🎓 Usage Training

Basic Command

Rscript generate_prisma_flowchart.R 122 122 117 5 5 2402 figures/

Parameter Explanation

Position Parameter Example Description
1 DB_RECORDS 122 Total records from database search
2 SCREENED 122 Records screened (title/abstract)
3 EXCLUDED 117 Records excluded after screening
4 FULLTEXT 5 Full-text articles assessed
5 INCLUDED 5 Studies included in meta-analysis
6 PARTICIPANTS 2402 Total N (optional)
7 OUTPUT_DIR figures/ Where to save (optional)

Extracting Numbers from Files

# Database records
DB_RECORDS=$(wc -l < 02_search/round-01/dedupe.bib | xargs)

# Screened
SCREENED=$(tail -n +2 03_screening/round-01/decisions.csv | wc -l | xargs)

# Excluded
EXCLUDED=$(grep -c "exclude" 03_screening/round-01/decisions.csv || echo 0)

# Fulltext
FULLTEXT=$((SCREENED - EXCLUDED))

# Included
INCLUDED=$(tail -n +2 05_extraction/round-01/extraction.csv | cut -d',' -f1 | sort -u | wc -l | xargs)

🔮 Future Enhancements (Optional)

  1. Python wrapper: prisma_flowchart.py to auto-extract numbers from project files
  2. Interactive customization: Edit labels directly in generated HTML
  3. Multiple databases: Support for displaying PubMed + Embase + Cochrane separately
  4. Update tracker: Auto-regenerate flowchart when screening/extraction files change
  5. Integration with ma-end-to-end: Automatic flowchart generation at each stage

📝 Reference

Original Publication:

Haddaway, N. R., Page, M. J., Pritchard, C. C., & McGuinness, L. A. (2022). PRISMA2020: An R package and Shiny app for producing PRISMA 2020-compliant flow diagrams, with interactivity for optimised digital transparency and Open Synthesis. Campbell Systematic Reviews, 18(2), e1230. https://doi.org/10.1002/cl2.1230

PRISMA 2020 Statement:

Page, M. J., McKenzie, J. E., Bossuyt, P. M., et al. (2021). The PRISMA 2020 statement: an updated guideline for reporting systematic reviews. BMJ, 372, n71. https://doi.org/10.1136/bmj.n71

✅ Completion Checklist

  • ✅ PRISMA2020 R package installed and tested
  • ✅ Example flowchart generated for ici-breast-cancer project
  • ✅ Automated R script created (generate_prisma_flowchart.R)
  • ✅ Comprehensive documentation written (prisma-flowchart-guide.md)
  • ✅ Quick reference card created (prisma-flowchart-quickstart.md)
  • ✅ Workflow integration completed (SKILL.md updated)
  • ✅ All output formats validated (PNG, PDF, SVG, HTML)
  • ✅ Test files cleaned up

🎉 Conclusion

The PRISMA2020 R package has been fully integrated into the meta-pipe workflow. Users can now generate publication-quality PRISMA 2020 flow diagrams with a single command, saving 30-60 minutes per diagram while ensuring 100% compliance with PRISMA 2020 standards.

Next Steps for Users:

  1. Read ma-search-bibliography/references/prisma-flowchart-quickstart.md
  2. Run the script after completing Stage 02 (Search)
  3. Update the flowchart after each subsequent stage
  4. Include the final flowchart as Figure 1 in your manuscript

Recommendation: Use the PNG version for manuscript submission and the HTML version for supplementary materials to maximize transparency.