Owner CANlab, extended by LaBGAS Repository CANlab_help_examples (fork) Folder Second_level_analysis_template_scripts/

Group-level analysis runs on the CANlab batch system, in our fork of CANlab_help_examples. The multivariate pipelines that sit alongside it — PLS-DA, PLSR, Elastic Net — are ours and live in LaBGAScore secondlevel/.

This stage is mostly CANlab’s. The batch system, the object model and the report machinery are documented at canlab.github.io/batch and canlab.github.io/docs. Read those alongside this page — what follows is an orientation, not a replacement.

Reference documentation. This page is an orientation. The authoritative guides live in the repositories:

The philosophy, briefly

The design goals behind the batch system explain why it looks the way it does:

  • Interactive analysis with reusable, well-vetted code rather than one-off scripts
  • Simple, readable scripts that a reviewer or a future lab member can follow
  • Date-stamped HTML reports carrying the figures, statistics and the code that produced them, archived as a durable record

That last point is the one that matters most in practice. A result from eighteen months ago can be inspected without re-running anything, and the report says exactly what was run.

How models are named

A second-level model is named after the first-level model it is built on:

model_<firstlevel number><letter>_<description>

model_2a_casecontrol_cov_scanner is built on firstlevel/model_2_basic, is the first second-level analysis derived from it, and controls for scanner. Scripts inside follow <proj>_secondlevel_m<N><letter>_s<step>_<template name>.m.

The first-level model is otherwise invisible from a second-level name, and it is the thing most likely to change underneath an analysis — a refit, a different noise model, a different high-pass filter. Two second-level results are only comparable if they share it, so the name records it. The description is a claim about the design: if the covariates change, the model gets a new name rather than a quietly widened old one.

Models named before this convention keep their names, because renaming would break the paths recorded inside saved .mat files and every published report. For those, s0 names the first-level options script it runs.

The five steps

1 · Create the analysis folder and run setup. Establishes the standard directory structure the later scripts expect.

2 · Edit the study configuration. Study metadata, paths, behavioural data, condition names and contrast definitions. This is where nearly all study-specific work happens — the rest of the pipeline is designed to need no editing.

3 · Prepare the data. The prep_* scripts load first-level contrast images into fmri_data objects, attach behavioural data, compute contrasts, and optionally apply published signatures or run machine-learning analyses. Results are cached so later steps are fast.

4 · Run results scripts on demand. Lettered scripts (c*, d*, f*, h*, k*) produce figures and tables — univariate maps, multivariate predictions, signature responses, network decompositions. Each works independently once the data are prepared, so you can iterate on one analysis without re-running everything.

5 · Publish. Scripts are run headless from the Linux command line via labgascore_run_headless.sh, which renders each into a date-stamped HTML report, records the commit of every dependency it reached, and fails loudly if the script errored — publish otherwise catches errors into the report and returns as if nothing were wrong.

What comes out

Five families of report: contrasts, signature responses, support vector machine analyses, network decomposition, and meta-analysis tests.

Inference

Group inference uses threshold-free cluster enhancement with permutation testing, which avoids committing to an arbitrary cluster-forming threshold. Published multivariate signatures from Neuroimaging_Pattern_Masks — NPS, SIIPS, PINES and others — are applied as a priori measures, which is a considerably stronger test than an exploratory whole-brain map.

Our multivariate pipelines

Three pipelines in LaBGAScore secondlevel/, each with its own usage guide in the repository and a page here:

Pipeline Use when Page
PLS-DA the outcome is categorical and you want a dense latent-variable solution PLS-DA
PLSR the outcome is continuous — symptom severity, ratings, hormone levels PLSR
Elastic Net the outcome is categorical and you want a sparse, feature-selecting solution Elastic Net

All three share the same design: repeated nested cross-validation, fold-wise covariate residualisation to avoid leakage, permutation testing, bootstrap confidence intervals, stability metrics and learning curves. A paired variant of PLS-DA handles within-subject designs.

The repository organises these into classes/, functions/ and scripts/, with README guides covering both the neuroimaging pipeline and the plotting for each method.

Next: PLS-DA Batch scripts Template scripts README Workflow protocol CANlab batch docs

Updated: