PRISM Documentation

PRISM (Psychological Research Information System & Management) is a validation and metadata framework for psychological experiment datasets. It extends the BIDS standard to support modalities common in psychological research—like surveys, biometrics, and eyetracking—while ensuring your data remains fully compatible with existing BIDS tools.

Important

PRISM is an add-on to BIDS, not a replacement. Your PRISM-validated datasets will still work with fMRIPrep, MRIQC, and all other BIDS apps.

Key Features:

• 🔍 Validation with structured error codes and auto-fix

• 📝 Self-documenting data with complete metadata in JSON sidecars

• 📊 Questionnaire scoring with recipes and SPSS export

• 🌐 Web interface (PRISM Studio) for easy project management

• ✨ 100+ survey templates in the official library

Getting Started

• What is PRISM?
  • PRISM is an Add-On, Not a Replacement
  • Key Benefits
  • Supported Modalities
  • Project Structure (YODA Layout)
  • Next Steps
• Installation
  • Quick Start
  • Requirements
  • Installation Options
  • Verify Installation
  • Daily Health Checks (Run-First)
  • Updating PRISM
  • Troubleshooting
  • Next Steps
• Quick Start
  • Step 1: Launch PRISM Studio
  • Step 2: Create a New Project
  • Step 3: Add Your Data
  • Step 4: Validate Your Dataset
  • Step 5: Run Scoring Recipes
  • What’s Next?
  • Common First-Time Issues
  • Getting Help
• Workshop
  • Overview
  • Getting Started
  • Exercise Summaries
  • Sample Data
  • Tips for Instructors
  • Additional Resources

PRISM Studio Guide

• PRISM Studio Overview
  • Launching PRISM Studio
  • Navigation
  • Home Page
  • Projects Page
  • Validator Page
  • Converter Page
  • Tools
  • Keyboard Shortcuts
  • Quitting PRISM Studio
  • Next Steps
• Projects
  • Creating Projects
  • Project Structure (YODA)
  • Dataset Description
  • Participants Files
  • NeuroBagel Compliance
• Converter
  • Supported Formats
  • Conversion Workflow
  • Output Structure
  • LimeSurvey Import
  • Participants Mapping
• Validator
  • Running Validation
  • Understanding Results
  • Common Error Codes
  • Auto-Fix
  • BIDS Validation
  • Validation Output Formats
• Tools
  • File Management
  • Survey Export
  • Recipes & Scoring
  • Template Editor
  • JSON Editor (Advanced)
  • AND Export
  • Quick Reference
• PRISM Studio (Web Interface)
  • 1) Start PRISM Studio
  • 2) Upload and validation workflow
  • 3) Understanding the results
  • 4) JSON editor
  • 5) Template Editor (Survey / Biometrics)
  • 6) NeuroBagel integration (participants)
  • 7) Methods Boilerplate Generator
  • 8) Survey Generator & Export
  • 7) Tips for first-time use

Reference

• CLI & Script Reference
  • 0) Environment requirement (.venv)
  • 1) prism.py — the dataset validator
  • 2) prism_tools.py — conversions, libraries, and helpers
  • 3) “Scripts” in scripts/
• Specifications and Schemas (PRISM vs BIDS)
  • 1) Conceptual model
  • 2) Schema versions
  • 3) Files PRISM expects in a dataset
  • 4) Filename conventions (high-level)
  • 5) Derivatives
  • 6) What is inside a PRISM schema?
  • 7) Detailed Schema Keys
  • 6) Internationalization (i18n)
  • 7) Detailed modality specifications
• PRISM Recipes Specification
  • Recipe Structure
  • Computation Logic: Derived vs. Scores
  • Available Methods
  • Handling Missing Data
  • Item Inversion (Reverse Coding)
  • Validation (When and How)
  • Output Structure
• Survey Library & Workflow
  • Library Location
  • Bilingual Templates (i18n)
• Error Codes Reference
  • PRISM Error Code System
  • Dataset Structure Errors (PRISM0xx)
  • File Naming Errors (PRISM1xx)
  • Sidecar/Metadata Errors (PRISM2xx)
  • Schema Validation Errors (PRISM3xx)
  • BIDS Compatibility Warnings (PRISM5xx)
  • Plugin/System Errors (PRISM9xx)
  • Legacy Error Names
  • Auto-Fix Support
  • Getting Help
• Participant Variable Mapping Guide
  • Overview
  • Quick Start
  • Complete Example: Wellbeing Survey
  • Mapping Specification Format
  • Standard PRISM Participant Variables
  • Value Mapping Reference
  • Workflow Integration
  • File Location
  • BIDS Compatibility
  • Troubleshooting
  • Examples
  • Best Practices
  • Getting Help
• BIDS Compliance Quick Reference
  • 🎯 At a Glance
  • 📋 Field Categories
  • 🔄 CITATION.cff Precedence Rules
  • 🔢 Field Type Conversions
  • 🛠️ Code Locations
  • 📝 Adding a New Metadata Field
  • 🧪 Testing Your Changes
  • ⚠️ Common Issues & Solutions
  • 🔗 Related Documentation
  • 🚀 Quick Debugging Commands
  • 📊 Field Summary Table
• Template Validation
  • What is Template Validation?
  • Quick Start
  • Template Structure
  • Study Metadata Fields
  • Item Definition Fields
  • Validation Rules
  • Python API
  • Error Types
  • Best Practices
  • Troubleshooting
  • Integration with PRISM Validation
  • See Also

Schema Specifications

• Survey
  • File Name Structure
  • Sidecar JSON (*_survey.json)
  • Example Sidecar
• Biometrics
  • File Name Structure
  • Sidecar JSON (*_biometrics.json)
  • Metric (Column) Definitions
  • Generating Templates from Excel
  • Example Sidecar
• Events (Super-BIDS)
  • File Name Structure
  • Sidecar JSON (*_events.json)
  • Example Sidecar

Advanced Topics

• LimeSurvey Integration Guide
  • Overview
  • 1. Preparation in LimeSurvey
  • 2. Exporting from LimeSurvey
  • 3. Converting to Prism JSON
  • 4. Finalizing the Dataset
  • 5. Reverse Engineering: JSON to LimeSurvey
  • 6. Advanced: Logic & Combining Surveys
  • Example Workflow
• Pavlovia Export Guide
  • Overview
  • Why Export to Pavlovia?
  • Architecture
  • Usage
  • Generated Structure
  • Question Type Mapping
  • Advanced Features
  • Limitations
  • Testing Before Upload
  • Integration with PRISM Workflow
  • See Also
• AND Export Guide
  • Quick Start
  • What Gets Generated
  • DataLad vs Git LFS
  • Workflow
  • Integration with PRISM Studio (Web UI)
  • Programmatic Usage
  • Troubleshooting
  • Related Documentation
  • Support
• Eye-Tracking TSV Normalization: Dots vs Empty Strings
  • Decision: Use Empty Strings (Not NaNs or Dots)
  • BIDS/TSV Standard for Missing Values
  • How to Handle Missing Values When Reading
  • Summary of Changes
  • Example: Before and After
  • Configuration in JSON Sidecar
  • References
• BIDS Compliance Auto-Mapping Implementation
  • 1. Overview
  • 2. BIDS Specification Mappings
  • 3. Implementation Details
  • 4. CITATION.cff Integration
  • 5. Validation & Error Handling
  • 6. Field Type Conversions
  • 7. Testing Checklist
  • 8. Known Limitations & Future Enhancements
  • 9. Implementation Files Summary
  • 10. References
  • 11. Approval & Sign-Off
• BIDS Compliance Auto-Mapping - Implementation Complete ✅
  • 🎯 Objectives Completed
  • 📊 Implementation Results
  • 🗂️ Files Modified
  • 🔗 Data Flow Verification
  • 📋 BIDS Field Mapping Summary
  • 🚀 Key Features Implemented
  • ✨ User Experience Improvements
  • 🧪 How to Verify Implementation
  • 📚 Documentation References
  • 🔮 Future Enhancements (Out of Scope)
  • ✅ Acceptance Criteria Met
  • 📞 Support & Questions
• Schema Versioning
• Windows Installation and Usage Guide
  • Overview
  • Option 1: Pre-Built Executable (For Regular Users)
  • Option 2: Development Installation (For Developers)
  • Windows-Specific Features (Both Installations)
  • Common Windows Issues and Solutions
  • File System Considerations
  • Performance Tips
  • Troubleshooting Virtual Environment Issues
  • Building Executables for Distribution (Developers Only)
  • Testing Windows Compatibility
  • Getting Help
  • Testing Windows Compatibility
  • File System Considerations
  • Performance Tips
  • Troubleshooting
  • Building for Distribution
  • Getting Help
• Building and Signing Prism Validator on Windows
  • Prerequisites
  • Code Signing for IT Departments
  • Quick Start (Building)
  • Output
  • Troubleshooting
  • Building for Distribution
  • Platform-Specific Notes
  • Next Steps
  • See Also
• GitHub Actions Code Signing - Complete Guide
  • Overview
  • Current Configuration Status
  • How It Works
  • Setup Instructions
  • What Gets Signed
  • Benefits of Code Signing
  • Troubleshooting
  • Verification Commands
  • Testing Signing Configuration
  • Cost and Limits
  • Alternative: Self-Signed Certificate
  • Security Best Practices
  • Support and Resources
  • Summary
• FAIR Data Principles Compliance
  • PRISM FAIR Data Policy
  • Implementation Roadmap

Development

• Changelog
• Changelog
• Creating GitHub Release v1.0.0 - Step-by-Step Guide
• Windows Testing Guide
• Windows Tests - Quick Reference
• Windows-Specific Test Suite - Summary
• Windows 11 VMware VM: Build & Test Portable ZIP
• Complete Windows Testing & Code Signing Summary

Indices and tables

• Index

• Search Page