PRISM Studio Documentation

Warning

Documentation Status: First Draft / Under Construction

This Read the Docs site is currently a working first draft. Content, examples, and page structure are actively being revised and may change without notice. If you spot inconsistencies, please treat this as expected during the drafting phase.

PRISM Studio is the software implementation of the PRISM (Psychological Research Information System Model) framework for psychological experiment datasets. It extends BIDS workflows for modalities common in psychological research-like surveys, biometrics, eyetracking, and environment-while ensuring your data remains fully compatible with existing BIDS tools.

Important

PRISM (the model) is an add-on to BIDS, not a replacement. PRISM Studio datasets still work with fMRIPrep, MRIQC, and other BIDS apps.

Key Features:

• 🔍 Validation with structured error codes and auto-fix

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

• 📊 Questionnaire scoring in PRISM Studio via recipes

• 📤 Export workflows in PRISM Studio (e.g., SPSS/integration formats)

• 🌐 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
  • Updating PRISM Studio
  • 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

Examples

• Examples
  • Workshop Walk-Through (Recommended)
  • What You Will Practice
• Workshop
  • Overview
  • Getting Started
  • Exercise Summaries
  • Sample Data
  • Tips for Instructors
  • Additional Resources

PRISM Studio Guide

• PRISM Studio Overview
  • Start Studio
  • Workflow Map
  • 1) Create or Open a Project
  • 2) Convert and Import Data
  • 3) Validate the Dataset
  • 4) Tools for Metadata and Scoring
  • 5) Export and Report
  • Frontend-First, Backend as Source of Truth
  • Common Problems
  • Related Pages
• Projects
  • Open the Projects Page
  • Create a New Project (Recommended)
  • Open an Existing Project
  • Edit Project Metadata in the Frontend
  • Recommended User Workflow
  • Optional CLI (Advanced)
  • Roadmap (User Feedback, 2026-03-16)
  • Lessons Learned (2026-03-16)
  • Next Sprint Handover (Token-Light)
• 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

CLI Workflows

• CLI Workflows
  • 1) Setup and Environment
  • 2) Run PRISM Studio from Terminal
  • 3) Validate a Dataset (CLI)
  • 4) Use prism_tools.py
  • 5) End-to-End Minimal Terminal Flow
  • 6) Daily Quality Commands
  • 7) Where to Go Next
• 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/

Reference

• 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
  • Import Template Layout
  • Multilingual Columns
  • 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
• Environment Specification
  • Scope
  • Position in PRISM
  • Typical Artifacts
  • Validation
  • Notes

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
• Schema Versioning
  • Available Versions
  • CLI Usage
  • Web Interface
  • Version Naming
  • Best Practices
  • Troubleshooting
• FAIR Data Principles Compliance
  • PRISM FAIR Data Policy

Indices and tables

• Index

• Search Page