Quick Start

Create your first PRISM project in 10 minutes using PRISM Studio.

Step 1: Launch PRISM Studio

Option A (Main): Prebuilt PRISM Studio

Open releases: https://github.com/MRI-Lab-Graz/prism-studio/releases
Download the package for your OS.
Extract the archive.
Launch PRISM Studio from the extracted folder.

Option B: Launch from Source Repository

cd prism-studio
python prism-studio.py

Your browser opens to http://localhost:5001. You will see the home page with quick actions.

Step 2: Create a New Project

Click Projects in the navigation bar
Select Create New Project
Enter your project details:
- Project Name: my_first_study (no spaces)
- Project Location: Choose a folder (e.g., Documents)
Click Create Project

This creates a YODA-structured project:

my_first_study/
├── dataset_description.json
├── participants.tsv
├── sub-001/
│   └── ...            ← Your BIDS/PRISM data goes here
├── code/              ← Analysis scripts
├── analysis/          ← Results
├── project.json       ← Project metadata
└── CITATION.cff       ← Citation information

Step 3: Add Your Data

Option A: Use the Converter (Recommended)

Click Converter in the navigation
Select your source file (Excel, CSV, SPSS)
Map columns to participant IDs and variables
Click Convert & Save to Project

Option B: Manual Import

Copy your data files to my_first_study/:

my_first_study/
├── dataset_description.json
├── participants.tsv
└── sub-001/
   └── survey/
      ├── sub-001_task-questionnaire_survey.tsv
      └── sub-001_task-questionnaire_survey.json

Step 4: Validate Your Dataset

Click Validator in the navigation
Your project folder is pre-selected
Click Validate
Review results:
- ✅ Green: Valid files
- ⚠️ Yellow: Warnings (should fix)
- ❌ Red: Errors (must fix)

Understanding Validation Results

Error Code	Meaning	How to Fix
PRISM101	Missing sidecar JSON	Create a `.json` file for your data
PRISM201	Invalid filename	Rename to `sub-XXX_task-YYY_modality.ext`
PRISM301	Missing required field	Add the field to your JSON sidecar

Click any error to see detailed explanations and auto-fix suggestions.

Step 5: Run Scoring Recipes

If you have survey data:

Go to Tools → Recipes & Scoring
Select your dataset
Choose recipes from the library (e.g., DEMO-5 Well-Being)
Click Run Recipes
Export results as SPSS or CSV

What’s Next?

Daily Health Commands (Recommended)

Use these in repo root before/after changes:

# fast sanity check (seconds)
bash scripts/ci/run_local_smoke.sh

# full required gate
bash scripts/ci/run_runtime_gate.sh

Hands-On Workshop

For a complete learning experience with example data:

# Open the workshop folder
cd examples/workshop

The workshop basics track includes 4 exercises:

Project Setup – YODA principles
Data Conversion – Excel to PRISM format
Metadata & Validation – Find and fix missing metadata
Recipes & Scoring – Calculate questionnaire scores and export

Optional add-ons (if time allows):

Participant Mapping – Demographic transformations
Templates – Build reusable survey metadata

See Workshop Guide for details.

Explore the Interface

Projects – Manage datasets and metadata
Converter – Import data from various formats
Validator – Understand validation errors
Tools – File management, templates, recipes

Use the CLI

For batch processing and scripting:

# Validate from command line
python prism-validator /path/to/project

# Run all recipes
python prism_tools.py recipes survey --prism /path/to/project --format save

See CLI Reference for all commands.

Common First-Time Issues

“No files found in dataset”

Make sure your data is in the project root (next to project.json), not in a nested rawdata/ subfolder.

“Missing dataset_description.json”

Create this required file in your project root:

{
  "Name": "My Study",
  "BIDSVersion": "1.9.0",
  "DatasetType": "raw"
}

“Invalid filename pattern”

Files must follow BIDS naming:

sub-<ID>_[ses-<session>_]task-<task>_<modality>.<ext>

Examples:

✅ sub-001_task-depression_survey.tsv
✅ sub-001_ses-01_task-anxiety_survey.tsv
❌ participant1_depression.tsv

Getting Help

Documentation: You’re reading it! Use the sidebar to navigate.
Workshop: examples/workshop/ has step-by-step exercises
Issues: Report bugs or request features at https://github.com/MRI-Lab-Graz/prism-studio/issues