Tutorial

Prepare tutorials

• Prepare — fMRI GLM
  • What are we preparing?
  • How the pipeline works
  • Word-Center (WC) mode
  • Relevant config keys
  • API reference
• Prepare — DWI
  • What are we preparing?
  • How the pipeline works
  • Supported containers and their required inputs
  • API reference
• Prepare — Retinotopy (PRF)
  • What are we preparing?
  • How the pipeline works
  • API reference

---

This page walks through a complete run from scratch using rtppreproc as the example pipeline. The same steps apply to all other pipelines — only the config values change.

Step 1 — Copy the example configs

Copy the bundled example config files to your working directory (we recommend basedir/code/):

lc copy_configs --output /scratch/tlei/VOTCLOC/code/

This gives you:

• lc_config.yaml — main config file

• subseslist.txt — subject/session list

• rtppreproc.json (and others) — container-specific parameter files

Step 2 — Edit lc_config.yaml

Open lc_config.yaml and set at minimum:

general:
  basedir: /scratch/tlei/VOTCLOC
  bidsdir_name: BIDS
  container: rtppreproc
  analysis_name: main
  host: DIPC
  deriv_layout: legacy
  force: True

container_specific:
  rtppreproc:
    version: 1.2.0-3.0.3
    precontainer_anat: freesurferator_0.2.1_7.4.1
    anat_analysis_name: main
    rpe: True

host_options:
  DIPC:
    manager: slurm
    cores: 20
    memory: 32G
    partition: general
    qos: regular
    walltime: '10:00:00'

See Configuration Reference for a full reference of all keys.

Step 3 — Edit subseslist.txt

Set RUN = True for every subject/session you want to process:

sub,ses,RUN,dwi
01,T01,True,True
01,T02,True,True
02,T01,True,True

Tip

To generate a subseslist automatically from an existing BIDS directory:

lc gen_subses --basedir /scratch/tlei/VOTCLOC/BIDS --name subseslist.txt

Step 4 — Prepare

lc prepare \
  --lc_config or -lcc               /scratch/tlei/VOTCLOC/code/lc_config.yaml \
  --sub_ses_list or -ssl            /scratch/tlei/VOTCLOC/code/subseslist.txt \
  --container_specific_config or -cc /scratch/tlei/VOTCLOC/code/rtppreproc.json

prepare will:

1. Validate that all required input files exist for each session.

2. Create the analysis directory under BIDS/derivatives/rtppreproc-1.2.0-3.0.3/analysis-main/.

3. Freeze copies of all your configs into analysis-dir.

4. Generate per-subject launch scripts in analysis-dir/job_scripts_<timing>/.

5. Write a cleaned subseslist.txt (blocking failures excluded).

6. Print a Rich summary table showing the status of every subject/session.

If any subjects have blocking issues they will be listed clearly and excluded from the cleaned subseslist.txt — all other subjects proceed.

Step 5 — Run

First do a dry run to verify what would be submitted:

lc run --workdir or -w /scratch/tlei/VOTCLOC/BIDS/derivatives/rtppreproc-1.2.0-3.0.3/analysis-main

Then submit for real:

lc run --workdir or -w /scratch/tlei/VOTCLOC/BIDS/derivatives/rtppreproc-1.2.0-3.0.3/analysis-main \
       --run_lc or -R

Jobs are submitted with sbatch (SLURM), qsub (SGE), or run directly via bash (local), depending on host_options.manager.

Step 6 — QC

After jobs finish:

lc qc --workdir or -w /scratch/tlei/VOTCLOC/BIDS/derivatives/rtppreproc-1.2.0-3.0.3/analysis-main

This will:

• Print a pass/fail table for every subject/session.

• Write a qc_TIMESTAMP.log under analysis-dir/logs/.

• Write analysis-dir/failed_subseslist.txt for any failures.

Re-running failures

Pass the QC-generated failed list straight back into prepare:

lc prepare \
  --lc_config                /scratch/tlei/VOTCLOC/code/lc_config.yaml \
  --sub_ses_list             /scratch/.../analysis-main/failed_subseslist.txt \
  --container_specific_config /scratch/tlei/VOTCLOC/code/rtppreproc.json

Then run and QC again as normal.

Using the integrity checker

The checker tool validates completeness across your whole dataset independently of the launcher:

checker --spec fmriprep \
        --bids-dir /scratch/tlei/VOTCLOC/BIDS \
        --sub-ses-list /scratch/tlei/VOTCLOC/code/subseslist.txt \
        --output-dir /scratch/tlei/VOTCLOC/code/qc/

It produces three output files:

• Brief CSV — one row per subject/session, pass/fail summary

• Detailed log — indexed list of all missing files

• Matrix CSV — subjects × sessions pivot table (1 = complete, 0.5 = partial, 0 = missing), ready to import into Google Sheets

Supported specs: bids, fmriprep, glm, prf, prfprepare, prfanalyze, bidsdwi, rtp.