`hypline denoise`¶

Regress nuisance regressors out of preprocessed BOLD, writing a denoised derivative. denoise reads fMRIPrep's preprocessed BOLD together with the nuisance regressors you select, and produces a desc-denoised BOLD under the derivatives/hypline/ tree.

hypline denoise <dataset-root> [--columns … | --compcor … | --custom-sources …] [OPTIONS]

Nuisance regressors come from two channels, stacked into one regressor matrix:

fMRIPrep's confounds table, read natively — --columns / --compcor select columns directly from each run's desc-confounds_timeseries.tsv. No intermediate hypline file is generated.
Custom nuisance files under nuisance/ — --custom-sources / --custom-columns select run-level regressors you supply yourself (e.g. physiological recordings).

Inputs¶

Preprocessed BOLD under derivatives/fmriprep/ — volumetric desc-preproc .nii.gz, or surface .func.gii (named by space/hemi, with no desc), selected by --space.
fMRIPrep confounds table (desc-confounds_timeseries.tsv, with its .json sidecar) beside the BOLD — read directly when you pass --columns / --compcor. The sidecar is always read (it carries the CompCor metadata), so it must be present even for a --columns-only run.
Custom nuisance files under nuisance/ — read only when you pass --custom-sources.

<dataset-root>/
├── derivatives/fmriprep/sub-031/ses-1/func/
│   ├── sub-031_ses-1_task-conv_run-1_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
│   ├── sub-031_ses-1_task-conv_run-1_desc-confounds_timeseries.tsv
│   └── sub-031_ses-1_task-conv_run-1_desc-confounds_timeseries.json   # required with --columns/--compcor
└── nuisance/sub-031/ses-1/physio-v1/                                  # optional, user-supplied
    └── sub-031_ses-1_task-conv_run-1_nuis-physio_desc-v1_timeseries.tsv

Options¶

Option	Description	Default
`--columns`	Comma-separated fMRIPrep confound columns to regress out (see below)	Speer et al. 2024 set (when no channel given)
`--compcor`	Comma-separated CompCor selectors (see below)	none
`--custom-sources`	Comma-separated `nuisance/` sources as `<kind>[-<desc>]`; requires `--custom-columns`	none
`--custom-columns`	Column names to select from the `--custom-sources` files; requires `--custom-sources`	none
`--space`	BOLD space to clean: `fsaverage5`, `fsaverage6`, `MNI152NLin6Asym`, `MNI152NLin2009cAsym`	`fsaverage6`
`--sub-ids`	Comma-separated subject IDs to process; omit for all	all
`--desc`	Output `desc` entity tag (alphanumeric); output lands as `desc-<desc>`. A distinct value keeps separate nuisance-config variants from overwriting (e.g. `--desc motionOnly`)	`denoised`
`--data-filters`	Narrow to specific runs/conditions — see Segments and metadata	none
`--force`	Overwrite existing outputs (default skips them)	off

No nuisance channel is required. When you pass none of --columns, --compcor, or --custom-sources, denoise falls back to the Speer et al. 2024 default set: motion and WM/CSF signal (each with squared and derivative expansions) plus cosine drift. An explicit --compcor or --custom-sources means you are picking your own model, so the default is left out rather than composed onto it.

--columns accepts exact column names from the fMRIPrep table (trans_x, rot_x, …) plus group prefixes that expand to every matching column (cosine → all cosine regressors, motion_outlier → all motion-outlier columns).

--compcor selects principal components using <type>:<mask>:<n> tokens:

Token	Meaning
`a:CSF:5`	top-5 anatomical CompCor components in the CSF mask
`a:WM:5`	top-5 anatomical components in the white-matter mask
`t::10`	top-10 temporal CompCor components (no mask)
`a:CSF:0.5`	enough CSF components to explain 50% of variance

<type> is a (anatomical, mask required) or t (temporal, no mask). <n> is a top-N integer, or a fraction between 0 and 1 for a variance threshold.

--custom-sources / --custom-columns pull run-level regressors from the nuisance/ area. Each source is a <kind> or <kind>-<desc> token naming a nuisance/<kind>[-<desc>]/ directory; --custom-columns then selects columns from the horizontal concat of all named sources. The two must be given together.

Authoring a nuisance/ file

Custom nuisance files are yours to create — hypline never writes them. Each must be a tab-separated .tsv with the _timeseries suffix and a nuis-<kind> entity, e.g. sub-031_ses-1_task-conv_run-1_nuis-physio_desc-v1_timeseries.tsv, placed in nuisance/sub-031/ses-1/<kind>[-<desc>]/. It is a wide table: one named column per regressor, one row per TR (row count must match the BOLD run). Every value must be finite — unlike the fMRIPrep table, there is no n/a convention, so a blank or non-numeric cell raises rather than being filled.

Things that must line up

Space must exist. --space must name a space present in your fMRIPrep outputs. It defaults to the surface space fsaverage6, cleaned per hemisphere automatically; volumetric spaces (MNI152*) are also supported.
Column names must be unique across all channels (fMRIPrep and custom); a collision raises rather than silently dropping one.
TR counts must match. Every selected regressor channel and the BOLD must have the same number of TRs, or denoise raises.

Example¶

Clean BOLD for all subjects with the default Speer et al. 2024 confound set — pass no nuisance channel at all. --space defaults to the surface fsaverage6, so it too can be omitted:

hypline denoise data/

Or name your own motion + drift model explicitly:

hypline denoise data/ \
  --columns trans_x,trans_y,trans_z,rot_x,rot_y,rot_z,cosine

Add CompCor components, and a custom physiological regressor from nuisance/:

hypline denoise data/ \
  --columns trans_x,trans_y,trans_z,rot_x,rot_y,rot_z,cosine \
  --compcor a:CSF:5,a:WM:5 \
  --custom-sources physio-v1 \
  --custom-columns resp,cardiac

Clean only run 1 of subjects 031 and 032:

hypline denoise data/ \
  --columns trans_x,trans_y,trans_z,rot_x,rot_y,rot_z,cosine \
  --sub-ids 031,032 \
  --data-filters run-1

Outputs¶

The denoised BOLD is written to its own derivatives/hypline/ tree, mirroring fMRIPrep's sub-XX/[ses-YY/]func/ shape and preserving the source's full BOLD identity — only the desc entity (desc-denoised) and the root differ from the source:

<dataset-root>/derivatives/hypline/sub-031/ses-1/func/
├── sub-031_ses-1_task-conv_run-1_space-MNI152NLin2009cAsym_desc-denoised_bold.nii.gz    # volumetric output
└── sub-031_ses-1_task-conv_run-1_space-MNI152NLin2009cAsym_desc-denoised_bold.json      # sidecar

A surface run (--space fsaverage6, the default) instead writes a per-hemisphere .func.gii pair carrying the source's space/hemi entities plus desc-denoised, e.g. sub-031_ses-1_task-conv_run-1_hemi-L_space-fsaverage6_desc-denoised_bold.func.gii.

The output keeps the input's dimensions; only the signal values change. Each run gets a per-file .json sidecar recording its Sources (a bids: URI to the source BOLD), the resolved cleaning settings, and the hypline version. On first output, hypline stamps a derivatives/hypline/dataset_description.json (written once, left alone thereafter).

Denoised BOLD lives in its own tree rather than beside its fMRIPrep source because denoising is hypline's own pipeline, not a continuation of fMRIPrep. A separate tree carries an honest GeneratedBy: hypline provenance instead of inheriting fMRIPrep's.

Common errors¶

What you see	Cause	Fix
`--custom-sources and --custom-columns must be given together`	One of the custom-nuisance options was passed without the other.	Supply both, or neither.
A `--custom-sources` source resolves to 0 (or multiple) files	A source names a `nuisance/<kind>[-<desc>]/` directory that does not exist (or matches more than one file per run).	Check the source spelling against your `nuisance/` directories.
`Unequal number of TRs between BOLD and nuisance`	A regressor channel has a different row count than the BOLD it is paired with.	Confirm the fMRIPrep confounds table and any custom nuisance files span every TR of the run.
Command finishes, but no `desc-denoised` files appear	`--space` names a valid space that is absent from your fMRIPrep outputs, so nothing matched.	Pass a `--space` you actually preprocessed (check the `space-` entity on your fMRIPrep BOLD files).
`No subjects found — nothing to denoise`	No subjects under `derivatives/fmriprep/`, or `--sub-ids` / `--data-filters` excluded them all.	Confirm fMRIPrep outputs exist and that your filters are not too narrow.

hypline denoise¶