PRISM Studio

Psychological Research Information System Model

PRISM Studio is a comprehensive tool for managing psychological research datasets built on the PRISM framework.

PRISM (Psychological Research Information System Model) extends BIDS for modalities such as surveys and biometrics while staying compatible with standard BIDS apps. PRISM Studio applies that model in practical web and CLI workflows for validation, conversion, and dataset management.

Core Features

• Dataset validation and conversion
• PRISM Studio web interface for interactive workflows
• CLI workflows for terminal users
• Survey and biometrics metadata support
• Local-first operation (data stays on your machine)

Feature Scope

To help third parties know what to rely on, PRISM's features fall into three tiers:

Tier	Meaning	Examples
Core loop	The primary supported workflow; breaking changes here get release notes and migration guidance.	Survey conversion, dataset validation, DataLad-tracked provenance for mutations and recipe scoring, entity/filename rules (entities.schema.json)
Supported	Deliberately-scoped bridges and integrations; stable, but intentionally narrower than the core loop.	BIDS phenotype/ export/import bridge (lossy by design — see ROADMAP.md Phase 1), recipe/derivative scoring
Experimental	Works, but has known rough edges or limited validation; use with care and report issues.	The Type-7 multiplexed decoder in the Varioport physio converter (flagged "QC required" in code)

See ROADMAP.md for the reasoning behind each scope decision.

Pre-built Binaries

Download the latest release from the Releases page.

Platform	Binary	Notes
macOS	prism-studio-macOS-AppleSilicon.zip	Apple Silicon (M1/M2/M3/M4)
macOS	prism-studio-macOS-AppleIntel.zip	Intel Macs
Windows	prism-studio-Windows.zip	x64
Linux	prism-studio-Linux.zip	x64

macOS first launch: if Gatekeeper blocks the app, run Prism Studio Installer.app from the extracted release folder (fallback: Open Prism Studio.command).

Installation

Prerequisite

• Python 3.10 or newer is required for source installation (Python 3.9 is not supported).

Using Pre-built Binaries (Recommended)

Download the latest release for your platform from the Releases page.

From Source

One-time setup from repository root.

macOS/Linux:

bash setup.sh

Windows (PowerShell):

.\setup.ps1

For detailed installation instructions, see the documentation.

Quick Usage

Run via RTK (recommended)

After setup and virtual environment activation, use the rtk command for common workflows:

rtk studio
rtk validator /path/to/dataset --bids
rtk tools --help
rtk test -q
rtk coverage
rtk codecov upload-process
rtk git status

Run PRISM Studio (Web)

python prism-studio.py

Open http://127.0.0.1:5001 if it does not open automatically.

For best performance, use a Chromium-based browser (Chrome, Edge, Brave, etc.). Safari can be significantly slower for local apps like PRISM Studio, especially with iCloud Private Relay or "Hide IP address from trackers" enabled - turn those off for this site, or switch browsers, if pages feel slow to load.

Pre-built binaries open PRISM Studio in its own app window by default instead of a browser tab (a native WebKit window on macOS; a tab-less Chromium/Edge "app mode" window on Windows and Linux). Pass --browser to open it in your default browser instead, --window to force the app window when running from source, or --no-browser to skip auto-opening either. If no suitable window backend is available, it falls back to opening your default browser.

Run PRISM Validator (CLI)

python prism-validator /path/to/dataset

Run PRISM Validator (Docker)

A slim, standalone validator image (just the CLI validation engine - no Flask, pandas, or datalad) is published automatically to GHCR on every release:

docker pull ghcr.io/mri-lab-graz/prism-validator:latest
docker run --rm -v "$(pwd)":/data:ro ghcr.io/mri-lab-graz/prism-validator:latest /data

Or build it locally from this repo:

docker build -t prism-validator .
docker run --rm -v "$(pwd)":/data:ro prism-validator /data

For CI, add --json or --format junit|sarif|markdown|csv for machine-readable output (printed to stdout by default - exit code is 0 when the dataset is valid, 1 otherwise). Avoid the -o FILE flag with a bind-mounted dataset: the container writes as root, so any file it creates inside the mount ends up root-owned on the host. Redirect from your shell instead, e.g. docker run ... --format junit > report.xml.

For GitHub Actions, action.yml wraps the same image as a one-step Action (uses: MRI-Lab-Graz/prism-studio@main) — see official/anc_templates/example-github-actions.yml for a full workflow. For GitLab CI (which can't consume a GitHub Action), see official/anc_templates/example-gitlab-ci.yml for the equivalent direct Docker invocation.

Run PRISM Tools (CLI)

python prism_tools.py --help

Documentation

Comprehensive documentation is available on ReadTheDocs.

Report an Issue

Use the Issues tab to report bugs or request features: https://github.com/MRI-Lab-Graz/prism-studio/issues

Include these details so we can reproduce quickly:

• Your OS and Python version
• The exact command you ran
• The full error message or screenshot
• A small dataset example (if possible)

Citation

See CITATION.cff for citation metadata.

License

See LICENSE.