CLI & Script Reference

This page is the detailed reference for PRISM’s command-line tools and scripts.

For a first-time, step-by-step narrative: see QUICK_START.md.
For specification / schema details: see SPECIFICATIONS.md.
For derivative scoring recipes: see RECIPES.md.

Run-first daily checks (repo root):

# fast sanity
bash scripts/ci/run_local_smoke.sh

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

0) Environment requirement (`.venv`)

Both prism.py and prism_tools.py enforce running from the repo-local virtual environment at ./.venv.

macOS / Linux:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

If you see:

❌ Error: You are not running inside the prism virtual environment!

activate the environment and retry.

1) `prism.py` — the dataset validator

Purpose

Validate a dataset against BIDS rules (optional) and PRISM schemas.
Produce machine-readable reports (JSON, SARIF, JUnit, Markdown, CSV).
Optionally apply safe auto-fixes (--fix).

Usage

python prism-validator /path/to/dataset

Options (complete)

Option	Meaning
`-v`, `--verbose`	Print detailed progress / scanning info.
`--schema-version VERSION`	Choose schema version (e.g. `stable`, `0.1`). Default is `stable`.
`--schema-info MODALITY`	Show schema details for a modality (currently a minimal stub).
`--list-versions`	List schema versions available in `schemas/`.
`--bids`	Run the standard BIDS validator in addition to PRISM validation.
`--bids-warnings`	Include warnings from BIDS validator output (default hidden).
`--no-prism`	Skip PRISM-specific checks (only BIDS if `--bids` is set).
`--validate-templates PATH`	Validate all survey/biometrics JSON templates in a library directory. See Template Validation for details.
`--build-environment`	Build a privacy-safe `*_environment.tsv` from `scans.tsv` anchors (no dataset validation run).
`--scans-tsv PATH`	Input scans table containing `filename` and `prism_time_anchor` (required with `--build-environment`).
`--environment-tsv PATH`	Output path for generated `*_environment.tsv` (required with `--build-environment`).
`--lat FLOAT`	Site latitude used by environment providers (required with `--build-environment`).
`--lon FLOAT`	Site longitude used by environment providers (required with `--build-environment`).
`--environment-providers ...`	Provider list for enrichment (default: `weather pollen air_quality`).
`--environment-cache PATH`	Cache file for provider responses (default: `.prism/environment_cache.json`).
`--json`	Output a JSON report to stdout (compact).
`--json-pretty`	Output a JSON report to stdout (pretty).
`--format {json,sarif,junit,markdown,csv}`	Set an explicit output format.
`-o FILE`, `--output FILE`	Write report to a file.
`--fix`	Apply auto-fixes for common issues (e.g., missing sidecars, `.bidsignore`).
`--dry-run`	Show what `--fix` would change without applying it.
`--list-fixes`	List which issue types are auto-fixable.
`--init-plugin NAME`	Create a validator plugin template at `<dataset>/validators/<NAME>.py`.
`--list-plugins`	List plugins loaded for a dataset.
`--no-plugins`	Disable plugin loading.
`--version`	Print PRISM version and exit.

Common examples

# Validate
python prism-validator /data/study-01

# Validate with BIDS validator too
python prism-validator /data/study-01 --bids

# Produce SARIF for GitHub Code Scanning
python prism-validator /data/study-01 --format sarif -o prism.sarif

# Validate survey templates in your project library
python prism-validator --validate-templates /code/library/survey

# Build privacy-safe environment table from scans anchors
python prism-validator \
  --build-environment \
  --scans-tsv /data/study-01/sub-01/ses-01/sub-01_ses-01_scans.tsv \
  --environment-tsv /data/study-01/sub-01/ses-01/environment/sub-01_ses-01_environment.tsv \
  --lat 47.07 \
  --lon 15.44

# Auto-fix (preview)
python prism-validator /data/study-01 --fix --dry-run

# Auto-fix (apply)
python prism-validator /data/study-01 --fix

Environment build mode (`--build-environment`)

Uses privacy-safe temporal anchors (prism_time_anchor) from scans.tsv.
Rejects raw time keys like date, datetime, timestamp, acquisition_time in input rows.
Runs independently from normal dataset validation (you can call it without positional dataset).
Current bundled providers: weather, pollen, air_quality.

2) `prism_tools.py` — conversions, libraries, and helpers

Purpose

prism_tools.py is the “Swiss Army Knife” for creating and managing PRISM-compatible content:

Import Survey and Biometrics libraries from Excel
Convert wide survey exports into a PRISM/BIDS-like dataset
Create survey derivatives (scores, reverse-coding) using Recipes
Convert Varioport .raw physio data into BIDS-like output
Generate manuscript-ready Methods boilerplate from your libraries
Manage and synchronize library templates

Usage

python prism_tools.py --help
python prism_tools.py <command> --help

Command overview

`recipes` (Derivatives)

Compute scores and subscales based on JSON recipe files.

# Compute survey scores
python prism_tools.py recipes surveys --prism /path/to/dataset

# Compute biometrics scores
python prism_tools.py recipes biometrics --prism /path/to/dataset

`library` (Management)

Tools for maintaining the PRISM library.

# Generate methods boilerplate
python prism_tools.py library generate-methods-text --output methods.md --lang en

# Fill missing schema keys in library files
python prism_tools.py library fill --modality survey --path library/survey/

# Synchronize keys across library files
python prism_tools.py library sync --modality biometrics --path library/biometrics/

# Generate a CSV catalog of the library
python prism_tools.py library catalog --input library/survey --output catalog.csv

The generated Methods boilerplate now summarizes the richer PRISM schema metadata (DOIs, licenses, age ranges, administration/scoring times, item counts, and access levels) alongside the existing citations.

`survey` / `biometrics` (Conversions)

Import data from external formats.

# Import from LimeSurvey (LSA)
python prism_tools.py survey import-limesurvey --input survey.lsa --output library/survey/

# Import from Excel
python prism_tools.py survey import-excel --input data.xlsx --output library/survey/

`convert physio`

Convert Varioport physiological recordings (.raw, .vpd) into outputs from either a sourcedata directory or a single file.

python prism_tools.py convert physio \
  --input ./sourcedata \
  --output ./rawdata \
  --task rest \
  --suffix ecg \
  --sampling-rate 256

`wide-to-long`

Convert a wide survey-style table into a long table by matching exact session indicators in column names.

# Inspect matches and rename preview without writing output
python prism.py wide-to-long \
  --input build/Limesurvey_gesamt.xlsx \
  --session-indicators T1_,T2_,T3_ \
  --inspect-only

# Convert and write a CSV
python prism.py wide-to-long \
  --input survey_export.xlsx \
  --output survey_export_long.csv \
  --session-indicators T1_,T2_,T3_

Key options:

--session-indicators: comma-separated exact tokens to match anywhere in the column name, for example T1_,T2_,T3_ or _pre,_post
--session-map: optional indicator-to-session mapping such as T1_:pre,T2_:post
--inspect-only: print indicator counts, rename preview, and ambiguity warnings without writing a file
--preview-limit: limit how many preview lines are printed
--force: overwrite an existing output file

Notes:

If the same indicator appears multiple times in a column name, the backend treats that as ambiguous and refuses conversion until the indicator is made more specific.
Output format is inferred from the output file extension: .csv, .tsv, or .xlsx.

`participants`

Participants helper commands used by the web converter backend and terminal workflows.

Important:

Use absolute file paths for --input.
--project can point to either a project root directory or a project.json file path.
participants convert writes participants.tsv into the resolved project root.

# Detect participant ID column
python prism_tools.py participants detect-id \
  --input /absolute/path/to/T1.xlsx \
  --sheet 0 \
  --separator auto \
  --json

# Preview participant extraction columns/rows
python prism_tools.py participants preview \
  --input /absolute/path/to/T1.xlsx \
  --sheet 0 \
  --id-column ID \
  --separator auto \
  --project /absolute/path/to/my-project/project.json \
  --preview-limit 20 \
  --json

# Convert to participants.tsv under project root
python prism_tools.py participants convert \
  --input /absolute/path/to/T1.xlsx \
  --sheet 0 \
  --id-column ID \
  --separator auto \
  --project /absolute/path/to/my-project/project.json \
  --force \
  --json

`demo create`

Create a demo dataset for testing.

python prism_tools.py demo create --output archive/prism_demo_copy

`survey import-excel`

Import survey templates from an Excel codebook into a JSON library.

python prism_tools.py survey import-excel --excel surveys.xlsx --library-root library

`survey validate`

Validate survey library JSONs and enforce uniqueness constraints.

python prism_tools.py survey validate --library library/survey

`survey convert`

Convert a wide survey export (.xlsx or LimeSurvey .lsa) into a PRISM/BIDS-like dataset.

python prism_tools.py survey convert \
  --input survey_export.xlsx \
  --output /tmp/my_prism_dataset

Key options:

--library: select template folder
--lang: language selection for i18n templates (de default; auto for .lsa)
--unknown {error,warn,ignore}: how to handle unmapped columns
--dry-run: print mapping only
--force: allow writing into non-empty output directory

`survey import-limesurvey` / `survey import-limesurvey-batch`

Import LimeSurvey instruments into PRISM templates/datasets.

python prism_tools.py survey import-limesurvey --input instrument.lsa --output survey-ads.json

python prism_tools.py survey import-limesurvey-batch \
  --input-dir ./limesurvey_exports \
  --output-dir ./my_dataset \
  --session-map t1:ses-1,t2:ses-2,t3:ses-3

`survey i18n-migrate` / `survey i18n-build`

Create and compile i18n-capable survey templates.

# Create i18n source templates (no translation added automatically)
python prism_tools.py survey i18n-migrate --src library/survey --dst library/survey_i18n --languages de,en

# Compile i18n templates for one target language
python prism_tools.py survey i18n-build --src library/survey_i18n --out library/survey_de --lang de --fallback de

`biometrics import-excel`

Import biometrics templates from an Excel codebook.

python prism_tools.py biometrics import-excel \
  --excel biometrics_codebook.xlsx \
  --sheet 0 \
  --library-root library

Key options:

--equipment: default Technical.Equipment
--supervisor: default Technical.Supervisor

`dataset build-biometrics-smoketest`

Generate a small biometrics dataset (templates + dummy data) for testing.

python prism_tools.py dataset build-biometrics-smoketest --output /tmp/prism_biometrics_smoketest

`derivatives surveys` / `derivatives biometrics`

Compute derived scores from TSVs in an already valid PRISM dataset.

# Survey derivatives
python prism_tools.py derivatives surveys --prism /path/to/dataset --format prism

# Biometric derivatives (supports xlsx, csv, save, r)
python prism_tools.py derivatives biometrics --prism /path/to/dataset --format xlsx

See RECIPES.md for details on how to write scoring recipes.

`library generate-methods-text`

Generate manuscript-ready methods text from libraries.

python prism_tools.py library generate-methods-text --output methods_en.md --lang en
python prism_tools.py library generate-methods-text --output methods_de.md --lang de

3) “Scripts” in `scripts/`

Environment enrichment scripts

Note: These utilities are currently parked under scripts/future_feature/. They are planned work and not part of the active web/CLI backend runtime path yet. For regular use, prefer prism_tools.py / backend modules.

PRISM now provides two separate scripts for environmental enrichment:

Scanner / DICOM workflow (site-fixed, scanner-related):

python scripts/future_feature/build_environment_from_dicom.py \
  --dicom /path/to/file.dcm \
  --dataset-root /path/to/dataset \
  --subject-id sub-01 \
  --session-id ses-01

Extracts acquisition timestamp from DICOM.
Uses hardcoded scanner site coordinates.
Writes directly to sub-*/ses-*/environment/*_environment.tsv.
Updates .bidsignore in dataset root.

Survey / international workflow (location provided per run):

python scripts/future_feature/build_environment_from_survey.py \
  --timestamp 2026-02-26T14:30:00 \
  --lat 47.0707 \
  --lon 15.4395 \
  --location-label survey-site \
  --output /path/to/sub-01_ses-01_environment.tsv \
  --subject-id sub-01 \
  --session-id ses-01

Uses provided timestamp + coordinates.
Designed for multi-country survey studies.
Writes one-row environment TSV for the specified context.

Both scripts query Open-Meteo hourly weather/air-quality/pollen APIs and include moon and sun context variables.

Most files under scripts/ are implementation details called by the CLIs.

If you’re a new user, prefer:

python prism-validator ... (validation)
python prism_tools.py ... (imports/conversion/derivatives)
python prism-studio.py (web interface)

If you are developing PRISM, refer to the repository changelog file (CHANGELOG.md).

CLI & Script Reference

0) Environment requirement (.venv)

1) prism.py — the dataset validator

Purpose

Usage

Options (complete)

Common examples

Environment build mode (--build-environment)

2) prism_tools.py — conversions, libraries, and helpers

Purpose

Usage

Command overview

recipes (Derivatives)

library (Management)

survey / biometrics (Conversions)

convert physio

wide-to-long

participants

demo create

survey import-excel

survey validate

survey convert

survey import-limesurvey / survey import-limesurvey-batch

survey i18n-migrate / survey i18n-build

biometrics import-excel

dataset build-biometrics-smoketest

derivatives surveys / derivatives biometrics

library generate-methods-text

3) “Scripts” in scripts/

Environment enrichment scripts

0) Environment requirement (`.venv`)

1) `prism.py` — the dataset validator

Environment build mode (`--build-environment`)

2) `prism_tools.py` — conversions, libraries, and helpers

`recipes` (Derivatives)

`library` (Management)

`survey` / `biometrics` (Conversions)

`convert physio`

`wide-to-long`

`participants`

`demo create`

`survey import-excel`

`survey validate`

`survey convert`

`survey import-limesurvey` / `survey import-limesurvey-batch`

`survey i18n-migrate` / `survey i18n-build`

`biometrics import-excel`

`dataset build-biometrics-smoketest`

`derivatives surveys` / `derivatives biometrics`

`library generate-methods-text`

3) “Scripts” in `scripts/`