Workshop

Learn PRISM through hands-on exercises with real example data.

Overview

The PRISM workshop takes you from raw survey data to a fully validated, scored, and exportable dataset. The core basics track uses 4 folders and optional extensions can be added if time allows.

Exercise

Topic

Duration

What You’ll Learn

0

Project Setup

15 min

YODA principles, folder structure

1

Data Conversion

30 min

Excel → PRISM format

2

Metadata & Validation

25 min

Find and fix metadata gaps

3

Recipes & Scoring

20 min

Calculate questionnaire scores

(Optional)

Participant Mapping

30-45 min

Demographic transformations

(Optional)

Templates

20 min

Create reusable item descriptions

Total time: ~90 minutes (core) / ~2 hours (with extensions)

Getting Started

1. Launch PRISM Studio

python prism-studio.py

Run the command from repository root.

2. Open the Workshop Materials

The workshop files are in:

examples/workshop/
├── exercise_0_project_setup/
├── exercise_1_raw_data/
├── exercise_2_hunting_errors/
├── exercise_3_using_recipes/
├── exercise_4_templates/             # optional
└── exercise_5_participant_mapping/   # optional extension

3. Follow the Handout

Open the complete guide: examples/workshop/WORKSHOP_HANDOUT_WELLBEING.md

Exercise Summaries

Exercise 0: Project Setup (YODA)

Goal: Create an organized research project following YODA principles.

Key Concepts:

  • Separation of raw data, code, and results

  • Project root contains the validated PRISM dataset

  • code/ contains analysis scripts

  • analysis/ contains derived results

Steps:

  1. Go to Projects → Create New Project

  2. Name your project wellbeing_study

  3. Observe the created folder structure

Exercise 1: Data Conversion

Goal: Convert wellbeing.xlsx to PRISM format.

Source Data: exercise_1_raw_data/raw_data/wellbeing.xlsx

participant_id

WB01

WB02

WB03

WB04

WB05

sub-001

3

4

3

4

3

sub-002

2

2

3

2

2

Steps:

  1. Go to Converter

  2. Load wellbeing.xlsx

  3. Map the participant_id column

  4. Select all WB* columns as survey items

  5. Convert and save to your project

Output: BIDS-structured files in sub-XXX/survey/ at project root

Exercise 2: Metadata & Validation

Goal: Validate the converted dataset and fix missing survey metadata.

Expected findings:

  • Missing study-level survey metadata

  • Missing item descriptions

  • Missing response-level labels

Steps:

  1. Go to Validator (/validate)

  2. Select your project folder and run validation

  3. Use exercise_4_templates/survey-wellbeing.json as source metadata

  4. Re-run validation until issues are resolved

Exercise 3: Recipes & Scoring

Goal: Calculate dummy wellbeing scores and export to SPSS.

Recipe: The demo total score is the sum of items (WB01-WB05).

{
  "RecipeName": "Workshop Dummy Wellbeing",
  "Scoring": {
    "wellbeing_total": {
      "operation": "sum",
      "items": ["WB01", "WB02", "WB03", "WB04", "WB05"]
    }
  }
}

Steps:

  1. Go to Tools → Recipes & Scoring

  2. Select your dataset

  3. Load recipe-wellbeing.json

  4. Run and export as SPSS (.save)

Optional Extension: Templates

Goal: Create survey metadata with item descriptions.

Why?: Templates make your data self-documenting. Anyone who opens your .json sidecar can understand what each item measures.

Steps:

  1. Go to Tools → Template Editor

  2. Create a new survey template

  3. Add items with questions in English and German

  4. Add response options with labels

  5. Save to your project

Optional Extension: Participant Mapping

Goal: Transform demographic encodings into standardized values.

Example:

  • Sex codes: 1/2/4 → M/F/O

  • Age text: "25 years" → 25

Steps:

  1. Add a participants_mapping.json in project code/library/

  2. Run conversion/validation again

  3. Confirm standardized participants.tsv output

Sample Data

The workshop uses a dummy wellbeing questionnaire for demonstration:

Item

Question

WB01

I felt motivated to start my daily tasks

WB02

I could focus well during important activities

WB03

I had enough energy throughout the day

WB04

I recovered well after work or study periods

WB05

I made time for activities I personally enjoy

Scale: 0 (At no time) to 5 (All of the time)

Scoring: Sum of WB01-WB05 (demo score)

Tips for Instructors

  1. Allow buffer time – Participants work at different speeds

  2. Show the raw data first – Context helps understanding

  3. Validate after Exercise 1 – See what’s missing before adding metadata

  4. Demo SPSS export – This is often the “wow” moment

  5. Have solutions ready – Each exercise folder includes a solution

Additional Resources