Core Concepts#

The three-phase workflow#

Every analysis in launchcontainers follows the same three phases:

lc prepare  →  lc run  →  lc qc

prepare: Reads your config files and subject/session list from basedir/code/. Validates that all required input files exist for each subject/session. Creates the analysis directory under BIDS/derivatives/, writes frozen copies of your configs into it, and generates per-subject HPC launch scripts.
run: Reads the prepared analysis directory — not your original config files. Submits the generated scripts to the HPC scheduler (SLURM, SGE, or local).
qc: After jobs finish, checks whether all expected output files were produced. Prints a pass/fail table, writes logs, and produces a failed_subseslist.tsv so that failed subjects can be re-submitted immediately.

The analysis directory as the source of truth#

A key design principle is that the analysis directory produced by prepare is fully self-contained and reproducible. Once prepare runs, run and qc only need its path — they never re-read your original basedir/code/ files.

BIDS/derivatives/
  rtppreproc-1.2.0-3.0.3/
    analysis-main/
      config/
        lc_config.yaml          ← frozen copy of your input config
        subseslist_input.tsv    ← original input subseslist
        subseslist.tsv          ← cleaned (blocking failures excluded)
      logs/
        prepare_TIMESTAMP.log
        run_TIMESTAMP.log
        qc_TIMESTAMP.log
      scripts/
        run_sub-01_ses-T01.sh
        run_sub-01_ses-T02.sh
      results/
        sub-01/ses-T01/
        ...
      failed_subseslist.tsv     ← written by qc on any failures

Issue severity levels#

During prepare, each subject/session check returns a list of issues with one of three severity levels:

Severity	Meaning	Behaviour
`blocking`	A required file is missing; cannot proceed	Subject/session excluded from the run
`warn`	Suspicious but not fatal	Subject/session included; issue logged
`auto_fix`	Issue can be resolved programmatically	Fix function is called automatically

Supported pipelines#

Container-based (DWI / structural)#

These pipelines run inside Apptainer/Singularity containers.

Container key	Purpose
`anatrois`	DWI preprocessing (legacy RTP)
`freesurferator`	FreeSurfer reconstruction and ROI operation
`rtppreproc`	DWI preprocessing (legacy RTP)
`rtp-pipeline`	DWI tractography (legacy RTP)
`rtp2-preproc`	DWI preprocessing (RTP2)
`rtp2-pipeline`	DWI tractography (RTP2)
`fMRIprep`	fMRI Preprocessing, including anatomical MRI processing with FreeSurfer
`prfprepare`	PRF prepare , preparing the events.tsv, getting preprocessed bold time series
`prfanalyze-vista`	PRF modeling, based on mrVista from Stanford
`prfresult`	Visulizing PRFresult on spheres and surface

Analysis-based (fMRI)#

These pipelines are managed by the PREPARER_REGISTRY and do not require a container.

Type key	Purpose
`glm`	First-level GLM (nilearn-based)
`presurfer`	MP2RAGE T1w image processing before freesurfer
`nordic_fmri`	NORDIC denoising on fMRI data using nordic_raw repo
`nordic_dwi`	NORDIC denoising on DWI data using nordic_raw repo
`to be added`	any analysis can be coded into single session running warappers.

Supported hosts#

Host key	Scheduler	Notes
`DIPC`	SLURM	`sbatch`, scratch filesystem at `/scratch`
`BCBL`	SGE	`qsub`, `long.q` queue, `/bcbl` filesystem
`local`	bash	Serial or parallel via concurrent.futures