Developers - API

The NiPreps community and contributing guidelines

fMRIPost-rapidtide is a NiPreps application, and abides by the NiPreps Community guidelines. Please, make sure you have read and understood all the documentation provided in the NiPreps portal before you get started.

Setting up your development environment

We believe that fMRIPost-rapidtide must be free to use, inspect, and critique. Correspondingly, you should be free to modify our software to improve it or adapt it to new use cases and we especially welcome contributions to improve it or its documentation.

We actively direct efforts into making the scrutiny and improvement processes as easy as possible. As part of such efforts, we maintain some tips and guidelines for developers to help minimize your burden if you want to modify the software.

Internal configuration system

A Python module to maintain unique, run-wide fMRIPost-rapidtide settings.

This module implements the memory structures to keep a consistent, singleton config. Settings are passed across processes via filesystem, and a copy of the settings for each run and subject is left under <fmriprep_dir>/sub-<participant_id>/log/<run_unique_id>/fmripost_rapidtide.toml. Settings are stored using ToML. The module has a to_filename() function to allow writing out the settings to hard disk in ToML format, which looks like:

This config file is used to pass the settings across processes, using the load() function.

Configuration sections

class fmripost_rapidtide.config.environment

Read-only options regarding the platform and environment.

Crawls runtime descriptive settings (e.g., default FreeSurfer license, execution environment, nipype and fMRIPost-rapidtide versions, etc.). The environment section is not loaded in from file, only written out when settings are exported. This config section is useful when reporting issues, and these variables are tracked whenever the user does not opt-out using the --notrack argument.

cpu_count = 2

Number of available CPUs.

exec_docker_version = None

Version of Docker Engine.

exec_env = 'posix'

A string representing the execution platform.

free_mem = 6.1

Free memory at start.

nipype_version = '1.10.0'

Nipype’s current version.

overcommit_limit = '50%'

Linux’s kernel virtual memory overcommit limits.

overcommit_policy = 'heuristic'

Linux’s kernel virtual memory overcommit policy.

templateflow_version = '24.2.2'

The TemplateFlow client version installed.

version = '0.1.dev66+g06816c1'

fMRIPost-rapidtide’s version.

class fmripost_rapidtide.config.execution

Configure run-level settings.

aggr_ses_reports = None

Maximum number of sessions aggregated in one subject’s visual report.

bids_database_dir = None

Path to the directory containing SQLite database indices for the input BIDS dataset.

bids_description_hash = None

Checksum (SHA256) of the dataset_description.json of the BIDS dataset.

bids_dir = None

An existing path to the dataset, which must be BIDS-compliant.

bids_filters = None

A dictionary of BIDS selection filters.

boilerplate_only = False

Only generate a boilerplate.

country_code = 'CAN'

Country ISO code used by carbon trackers.

debug = []

Debug mode(s).

derivatives = {}

Path(s) to search for pre-computed derivatives

fs_license_file = None

An existing file containing a FreeSurfer license.

classmethod init()

Create a new BIDS Layout accessible with layout.

layout = None

A BIDSLayout object, see init().

log_dir = None

The path to a directory that contains execution logs.

log_level = 25

Output verbosity.

low_mem = None

Utilize uncompressed NIfTIs and other tricks to minimize memory allocation.

md_only_boilerplate = False

Do not convert boilerplate from MarkDown to LaTex and HTML.

notrack = False

Do not collect telemetry information for fMRIPost-rapidtide.

output_dir = None

Folder where derivatives will be stored.

output_spaces = None

List of (non)standard spaces designated (with the --output-spaces flag of the command line) as spatial references for outputs.

participant_label = None

List of participant identifiers that are to be preprocessed.

reports_only = False

Only build the reports, based on the reportlets found in a cached working directory.

run_uuid = '20250701-130700_5b9f663b-2ddd-4f2d-9df3-533711c0846c'

Unique identifier of this particular run.

sloppy = False

Run in sloppy mode (meaning, suboptimal parameters that minimize run-time).

task_id = None

Select a particular task from all available in the dataset.

templateflow_home = PosixPath('/home/docs/.cache/templateflow')

The root folder of the TemplateFlow client.

track_carbon = False

Tracks power draws using CodeCarbon package.

work_dir = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/fmripost-rapidtide/checkouts/latest/docs/work')

Path to a working directory where intermediate results will be available.

write_graph = False

Write out the computational graph corresponding to the planned preprocessing.

class fmripost_rapidtide.config.workflow

Configure the particular execution graph of this workflow.

ampthresh = None

For refinement, exclude voxels with correlation coefficients less than AMP.

autorespdelete = None

Attempt to detect and remove respiratory signal that strays into the LFO band.

autosync = None

Estimate and apply the initial offsettime of an external regressor using the global crosscorrelation.

average_over_runs = False

Whether to average lag maps over runs or not. Disabled until it works.

bipolar = None

Bipolar mode - match peak correlation ignoring sign.

cifti_output = None

Generate HCP Grayordinates, accepts either '91k' (default) or '170k'.

confoundfile = None

Read additional (non-motion) confound regressors out of CONFFILE file.

confoundpowers = None

Include powers of each confound regressor up to order N.

convergencethresh = None

Continue refinement until the MSE between regressors becomes <= THRESH.

corrweighting = None

Method to use for cross-correlation weighting.

detrendorder = None

Set order of trend removal (0 to disable).

dummy_scans = None

Set a number of initial scans to be considered nonsteady states.

err_on_warn = False

Cast Rapidtide warnings to errors.

filterband = None

Filter data and regressors to specific band. Use “None” to disable filtering.

filterfreqs = None

Filter data and regressors to retain LOWERPASS to UPPERPASS.

filterstopfreqs = None

Filter data and regressors to with stop frequencies LOWERSTOP and UPPERSTOP.

fixdelay = None

Don’t fit the delay time - set it to DELAYTIME seconds for all voxels.

glmsourcefile = None

Regress delayed regressors out of FILE instead of the initial fmri file used to estimate delays.

globalpcacomponents = None

Number of PCA components used for estimating the global signal.

globalsignalmethod = None

The method for constructing the initial global signal regressor - straight summation.

lagmaxthresh = None

For refinement, exclude voxels with delays greater than MAX.

lagminthresh = None

For refinement, exclude voxels with delays less than MIN.

maxpasses = None

Terminate refinement after MAXPASSES passes, whether or not convergence has occurred.

noconfoundderiv = None

Toggle whether derivatives will be used in confound regression.

numnull = None

Estimate significance threshold by running NREPS null correlations.

numskip = None

When calculating the moving regressor, set this number of points to zero at the beginning of the voxel timecourses.

outputlevel = None

The level of file output produced.

pcacomponents = None

Number of PCA components used for refinement.

regressderivs = None

When doing final GLM, include derivatives up to NDERIVS order.

searchrange = None

Limit fit to a range of lags from LAGMIN to LAGMAX.

sigmalimit = None

Reject lag fits with linewidth wider than SIGMALIMIT Hz.

sigmathresh = None

For refinement, exclude voxels with widths greater than SIGMA seconds.

simcalcrange = None

Limit correlation calculation to data between timepoints START and END in the fmri file.

spatialfilt = None

Spatially filter fMRI data prior to analysis using GAUSSSIGMA in mm.

territorymap = None

This specifies a territory map. Each territory is a set of voxels with the same integral value.

timerange = None

‘Limit analysis to data between timepoints START and END in the fmri file.

class fmripost_rapidtide.config.nipype

Nipype settings.

crashfile_format = 'txt'

The file format for crashfiles, either text (txt) or pickle (pklz).

get_linked_libs = False

Run NiPype’s tool to enlist linked libraries for every interface.

classmethod get_plugin()

Format a dictionary for Nipype consumption.

classmethod init()

Set NiPype configurations.

memory_gb = None

Estimation in GB of the RAM this workflow can allocate at any given time.

nprocs = 2

Number of processes (compute tasks) that can be run in parallel (multiprocessing only).

omp_nthreads = None

Number of CPUs a single process can access for multithreaded execution.

plugin = 'MultiProc'

NiPype’s execution plugin.

plugin_args = {'maxtasksperchild': 1, 'raise_insufficient': False}

Settings for NiPype’s execution plugin.

remove_unnecessary_outputs = True

Clean up unused outputs after running

resource_monitor = False

Enable resource monitor.

stop_on_first_crash = True

Whether the workflow should stop or continue after the first error.

Usage

A config file is used to pass settings and collect information as the execution graph is built across processes.

from fmripost_rapidtide import config
config_file = config.execution.work_dir / '.fmripost_rapidtide.toml'
config.to_filename(config_file)
# Call build_workflow(config_file, retval) in a subprocess
with Manager() as mgr:
    from .workflow import build_workflow
    retval = mgr.dict()
    p = Process(target=build_workflow, args=(str(config_file), retval))
    p.start()
    p.join()
config.load(config_file)
# Access configs from any code section as:
value = config.section.setting

Logging

class fmripost_rapidtide.config.loggers

Keep loggers easily accessible (see init()).

cli = <Logger cli (WARNING)>

Command-line interface logging.

default = <RootLogger root (WARNING)>

The root logger.

classmethod init()

Set the log level, initialize all loggers into loggers.

• Add new logger levels (25: IMPORTANT, and 15: VERBOSE).

• Add a new sub-logger (cli).

• Logger configuration.

interface = <Logger nipype.interface (INFO)>

NiPype’s interface logger.

utils = <Logger nipype.utils (INFO)>

NiPype’s utils logger.

workflow = <Logger nipype.workflow (INFO)>

NiPype’s workflow logger.

Other responsibilities

The config is responsible for other conveniency actions.

• Switching Python’s multiprocessing to forkserver mode.

• Set up a filter for warnings as early as possible.

• Automated I/O magic operations. Some conversions need to happen in the store/load processes (e.g., from/to Path <-> str, BIDSLayout, etc.)

fmripost_rapidtide.config.dumps()

Format config into toml.

fmripost_rapidtide.config.from_dict(settings, init=True, ignore=None)

Read settings from a flat dictionary.

Parameters:

• setting (dict) – Settings to apply to any configuration

• init (bool or Container) – Initialize all, none, or a subset of configurations.

• ignore (Container) – Collection of keys in setting to ignore

fmripost_rapidtide.config.get(flat=False)

Get config as a dict.

fmripost_rapidtide.config.init_spaces(checkpoint=True)

Initialize the spaces setting.

fmripost_rapidtide.config.load(filename, skip=None, init=True)

Load settings from file.

Parameters:

• filename (os.PathLike) – TOML file containing fMRIPost-rapidtide configuration.

• skip (dict or None) – Sets of values to ignore during load, keyed by section name

• init (bool or Container) – Initialize all, none, or a subset of configurations.

fmripost_rapidtide.config.to_filename(filename)

Write settings to file.

Workflows

fMRIPost Rapidtide workflows

fmripost_rapidtide.workflows.base.init_fmripost_rapidtide_wf()

Build fMRIPost-rapidtide’s pipeline.

This workflow organizes the execution of fMRIPost-rapidtide, with a sub-workflow for each subject.

Workflow Graph

(Source code)

fmripost_rapidtide.workflows.base.init_single_subject_wf(subject_id: str)

Organize the postprocessing pipeline for a single subject.

It collects and reports information about the subject, and prepares sub-workflows to postprocess each BOLD series.

Workflow Graph

(Source code)

Parameters:

subject_id (str) – Subject label for this single-subject workflow.

Notes

1. Load fMRIPost-rapidtide config file.

2. Collect fMRIPrep derivatives. - BOLD file in native space. - Two main possibilities:

   1. bids_dir is a raw BIDS dataset and preprocessing derivatives are provided through --derivatives. In this scenario, we only need minimal derivatives.

   2. bids_dir is a derivatives dataset and we need to collect compliant derivatives to get the data into the right space.

3. Loop over runs.

4. Collect each run’s associated files. - Transform(s) to target spaces - Confounds file - Rapidtide uses its own standard-space edge, CSF, and brain masks,

   so we don’t need to worry about those.

5. Transform dseg from anat space to boldref space.

6. Run Rapidtide on boldref space data.

7. Warp derivatives (denoised BOLD, delay map, 4D regressor) to requested output spaces. Warp the denoised BOLD from boldref to target instead of warping preprocessed BOLD and then denoising.

8. Create reportlets.

fMRIPost-rapidtide workflows to run Rapidtide.