PRISM Documentation

PRISM is an independent, BIDS-compatible dataset validation tool for psychological experiments. It validates standard BIDS datasets and additionally enforces PRISM extensions (e.g., stricter metadata requirements for certain files and support for modalities like surveys and biometrics) while remaining compatible with BIDS tools/apps.

Key Features:

• Multi-modal validation: survey, physio, eyetracking, biometrics, events, anat, func, dwi, fmap

• Structured error codes: PRISM001-PRISM9xx with severity levels

• Auto-fix: Automatically fix common issues (--fix)

• Multiple output formats: JSON, SARIF, JUnit XML, Markdown, CSV

• Plugin system: Custom validators for project-specific rules

• REST API: Integrate validation into workflows

• Bilingual surveys: German + English templates in single JSON files

• Template Editor (Web UI): Value-only editing for Survey/Biometrics templates with schema guidance

Getting Started

• PRISM Walkthrough: A Comprehensive Guide for New Users
  • 1. What is PRISM?
  • 2. Installation
  • 3. Starting the Interfaces
  • 4. Data Preparation
  • 5. Using the PRISM Studio Web Interface
  • 6. Using the Terminal (CLI)
  • 7. What the Output Looks Like
  • 8. Computing Recipes (Scores & Subscales)
  • 9. Summary of Tools
• Quick Start
  • 1) Install (source checkout)
  • 2) Validate a dataset (CLI)
  • 3) Run the web interface
  • 4) Use PRISM tools
  • 5) Error Codes
• Installation
  • Prerequisites
  • Quick Install (Recommended)
  • Manual Installation
  • Verifying Installation
  • Troubleshooting
• Usage Guide
  • 🖥️ Web Interface (Recommended)
  • Notes
  • ⌨️ Command Line Interface (CLI)
  • 🔧 Auto-Fix Mode
  • 📄 Output Formats
  • 🔌 Plugin System
  • 📋 Project Configuration
  • 🌐 REST API
• Demo Data Guide
  • Overview
  • Excel Import Templates
  • Templates: Multilingual Survey & Biometrics
  • Raw Data: Source Files
  • Derivatives: Scoring Recipes
  • PRISM Structure Example
  • Flat Structure Example (Anti-Pattern)
  • Hands-On Tutorials
  • Summary
• Prism Tools (CLI)
  • Requirements
  • Physiological Data Conversion
  • Demo Dataset
  • Survey Library Management
  • Recipes (Derivatives)
  • Biometrics Library Management
  • Dataset Helpers
  • Manuscript methods boilerplate (scientific text)
• Survey Data Import Workflow
  • 1) Start from the provided Excel templates
  • 2) Survey Excel format (minimal vs advanced)
  • 3) Import the survey Excel into a library
  • 4) Convert wide survey exports into a dataset
  • 5) Validate
  • Biometrics (separate Excel)
• Survey Library & Workflow
  • Library Location
  • Bilingual Templates (i18n)
• 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

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
• 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/

Understanding the Data

• 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
• 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
• Survey
  • File Name Structure
  • Sidecar JSON (*_survey.json)
  • Example Sidecar
• Schema Versioning
• Schema Versioning Guide
  • Overview
  • Available Versions
  • Using Schema Versions
  • Version Naming Convention
  • Creating New Schema Versions
  • Best Practices
  • Migration Between Versions
  • Schema Version in Reports
  • FAQ
  • Version History
  • Related Documentation
• FAIR Data Principles Compliance
  • PRISM FAIR Data Policy
  • Implementation Roadmap

Troubleshooting

• 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

Advanced / Developer

• 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
• Windows Compatibility Summary
  • ✅ Completed Windows Compatibility Features
  • 🔄 Implementation Details
  • 📊 Test Results
  • 🎯 Windows-Specific Benefits
  • 🔧 Development Approach
  • 🚀 Future Enhancements
  • 📋 Validation
  • 📝 Migration Notes
• 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
• Implementation Summary
• Creating GitHub Release v1.0.0 - Step-by-Step Guide
  • Prerequisites
  • Step 1: Commit All Changes
  • Step 2: Create Git Tag
  • Step 3: Create GitHub Release
  • Step 4: Verify Release
  • Step 5: Post-Release Tasks
  • Troubleshooting
  • Quick Command Summary
  • Checklist
  • Next Steps
• Release Notes (v1.0.0)
• Changelog
• Changelog
  • [1.9.1] - 2026-01-21
  • [1.9.0] - 2026-01-21
  • [1.8.1] - 2026-01-15
  • [1.8.0] - 2026-01-15
  • [1.7.1] - 2026-01-12
  • [1.7.0] - 2026-01-12
  • [1.6.6] - 2026-01-02
  • [1.6.5] - 2025-12-25
  • [1.6.2] - 2025-12-24
  • [1.6.1] - 2025-12-22
  • [1.6.0] - 2025-12-20
  • 1.0.0 - 2025-10-09
  • Release Notes
  • [1.3.0] - 2025-11-28
• Read the Docs (RTD)
  • What RTD builds
  • Local build
  • RTD configuration

Indices and tables

• Index

• Module Index

• Search Page