API

Internal configuration system

A Python module to maintain unique, run-wide fMRIStroke 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 <fmristroke_dir>/sub-<participant_id>/log/<run_unique_id>/fmristroke.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 fmristroke.config.environment[source]

Read-only options regarding the platform and environment.

The environment section is not loaded in from file, only written out when settings are exported. This config section is useful when reporting issues.

cpu_count = 2

Number of available CPUs.

exec_env = 'posix'

A string representing the execution platform.

fmriprep_version = '23.0.2'

fMRIPrep’s version.

free_mem = 6.2

Free memory at start.

nipype_version = '1.8.6'

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 = '23.0.0'

The TemplateFlow client version installed.

version = '1.0.0'

*fmriStroke’s version.

class fmristroke.config.execution[source]

Configure run-level settings.

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.

fmriprep_dir = None

A path where fmriprep derivatives are found.

classmethod init()[source]

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.

output_atlases = None

List of pipelines designated (with the --output-atlases flag of the comand line) as atlases for connectivity

output_dir = None

Folder where derivatives will be stored.

output_pipelines = None

List of pipelines designated (with the --output-pipelines flag of the comand line) as pipelines for denoising

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_sessionlevel = False

Concatenate runs from the same session and task

run_uuid = '20260414-123233_84115847-4479-44d1-aebd-ba43e89303b7'

Unique identifier of this particular run.

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

The root folder of the TemplateFlow client.

work_dir = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/fmristroke/checkouts/latest/docs/work')[source]

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 fmristroke.config.workflow[source]

Configure the particular execution graph of this workflow.

atlases = None

Keeps the atlases instances for connectivity

conn_measure = None

Measure to use for connectivity

croprun = None

Crops n first volumes in fMRI run before concatenating when session-level is true

freesurfer = None

Wether freesurfer must be used

ica_method = None

ICA method to use

lower_cutoff = 0.2

Lower cutoff for compute_epi_mask

maxlag = None

Maxlag for hemodynamics computations

ncomp_method = None

Method to estimate components for lesion ICA

pipelines = None

Keeps the pipelines instances for denoising

spaces = None

Keeps the SpatialReferences instance keeping standard and nonstandard spaces.

upper_cutoff = 0.85

Upper cutoff for compute_epi_mask

class fmristroke.config.nipype[source]

Nipype settings.

crashfile_format = 'txt'

The file format for crashfiles, either text or pickle.

get_linked_libs = False

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

classmethod get_plugin()[source]

Format a dictionary for Nipype consumption.

classmethod init()[source]

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.

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.

fmristroke.config.dumps()[source]

Format config into toml.

fmristroke.config.from_dict(settings, init=True, ignore=None)[source]

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

fmristroke.config.get(flat=False)[source]

Get config as a dict.

fmristroke.config.init_spaces(checkpoint=True)[source]

Initialize the spaces setting.

fmristroke.config.load(filename, skip=None, init=True)[source]

Load settings from file.

Parameters:

  • filename (os.PathLike) – TOML file containing fMRIStroke 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.

fmristroke.config.to_filename(filename)[source]

Write settings to file.

Workflows

fMRIStroke base processing workflows

fmristroke.workflows.final.init_fmristroke_wf()[source]

Build fMRIStroke’s pipeline.

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

fmristroke.workflows.final.init_single_subject_wf(subject_id: str)[source]

Organize the preprocessing pipeline for a single subject.

It collects and reports information about the subject, and prepares sub-workflows to perform pipelines.. Functional is performed using a separate workflow for each individual BOLD series.

Parameters:

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

Parameters:

subjects_dir (str) – FreeSurfer’s $SUBJECTS_DIR.

Lesion preprocessing fMRI - BOLD signal workflows

Orchestrating the BOLD-preprocessing workflow

fmristroke.workflows.bold.base.init_lesion_preproc_wf(bold_file, boldref_file, boldmask_file, confounds_file, confounds_metadata)[source]

This workflow controls the lesion specific stages fMRIStroke.

Parameters:

  • bold_file – Path to NIfTI file

  • boldref_file – Path to NIfTI file

  • boldmask – Path to NIfTI file

  • confounds_file – Path to tsv file

  • confounds_metadata – Path to json file describin confounds

Parameters:

  • bold_t1 – BOLD series NIfTI file in anatomical space

  • boldref_t1 – BOLD reference NIfTI file in anatomical space

  • boldmask_t1 – BOLD mask in anatomical space

  • t1w_preproc – Bias-corrected structural template image

  • t1w_mask – Mask of the skull-stripped template image

  • t1w_dseg – Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)

  • t1w_aseg – Segmentation of structural image, done with FreeSurfer.

  • t1w_aparc – Parcellation of structural image, done with FreeSurfer.

  • t1w_tpms – List of tissue probability maps in T1w space

  • confounds_file – confounds file

  • roi – ROI mask

Parameters:

  • roi_mask_t1 – ROI mask in T1w space

  • roi_mask_std – roi mask, resampled to template space

  • confounds – TSV of confounds

  • confounds_metadata – Confounds metadata dictionary

fmristroke.workflows.bold.base.init_func_lesion_derivatives_wf(bids_root: str, output_dir: str, spaces: SpatialReferences, pipelines: Pipelines, atlases: Atlases, conn_measure: List[str], name='func_lesion_derivatives_wf')[source]

Set up a battery of datasinks to store derivatives in the right location.

Parameters:

  • bids_root (str) – Original BIDS dataset path.

  • metadata (dict) – Metadata dictionary associated to the BOLD run.

  • output_dir (str) – Where derivatives should be written out to.

  • spaces (SpatialReferences) – A container for storing, organizing, and parsing spatial normalizations. Composed of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs (e.g., MNI152Lin, MNI152NLin6Asym, MNIPediatricAsym), nonstandard references (e.g., T1w or anat, sbref, run, etc.), or a custom template located in the TemplateFlow root directory. Each Reference may also contain a spec, which is a dictionary with template specifications (e.g., a specification of {'resolution': 2} would lead to resampling on a 2mm resolution of the space).

  • name (str) – This workflow’s identifier (default: func_lesion_derivatives_wf).

Confounds generation

fmristroke.workflows.bold.confounds.init_confs_wf(mem_gb: float, metadata: dict, ica_method: str = 'canica', freesurfer: bool = False, ncomp_method: str = 'varexp', lower_cutoff: float = 0.2, upper_cutoff: float = 0.85, name: str = 'confounds_wf')[source]

Build a workflow to generate and write out confounding signals.

This workflow calculates roi related confounds based on the ones obtained by fmriprep for a BOLD series from stroke patients, and aggregates them into a TSV file, for use as nuisance regressors in a GLM. The following confounds are added, with column headings in parentheses:

  1. Region-wise average signal excluding lesion signal (csf_nolesion, white_matter_nolesion, combined_nolesion)

  2. Region-wise average signal in roi (lesion)

  3. Region-wise average signal including roi (csf_lesion, combined_lesion)

  4. ICA based lesion confounds

Parameters:

  • mem_gb (float) – Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV

  • metadata (dict) – BIDS metadata for BOLD file

  • lower_cutoff (float) – Lower cutoff passed to nilearn.masking.compute_epi_mask()

  • upper_cutoff (float) – Upper cutoff passed to nilearn.masking.compute_epi_mask()

  • name (str) – Name of workflow (default: bold_confs_wf)

Parameters:

  • bold – BOLD image, after the prescribed corrections (STC, HMC and SDC) when available.

  • t1w_mask – Mask of the skull-stripped template image

  • t1w_mask_lesion – Mask of the lesion in T1w space

  • t1w_tpms – List of tissue probability maps in T1w space

  • t1_bold_xform – Affine matrix that maps the T1w space into alignment with the native BOLD space

  • confounds_file – TSV of all aggregated confouconf_corr_plotnds computed by fmriprep

Parameters:

  • confounds_file – TSV of all aggregated confounds

  • confounds_metadata – Confounds metadata dictionary.

  • ica_plot – Reportlet visualizing ICA components included in confounds files.

Hemodynamics

fmristroke.workflows.bold.lagmaps.init_hemodynamic_wf(mem_gb: float, metadata: dict, maxlag: int = 10, name: str = 'hemodynamic_wf')[source]

Build a workflow to generate lagmaps.

This workflow calculates the hemodynamic lag for stroke patients. as recommended by Siegel et al. (2017) https://pubmed.ncbi.nlm.nih.gov/28541130/ It uses the existing tool RapidTide that calculates a similarity function between a “probe” signal and every voxel of a BOLD fMRI dataset. It then determines the peak value, time delay, and width of the similarity function to determine when and how strongly that probe signal appears in each voxel. For details about the method visit : https://rapidtide.readthedocs.io/en/latest/

Parameters:

  • mem_gb (float) – Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV

  • metadata (dict) – BIDS metadata for BOLD file

  • maxlag (obj: int) – Max lag to compute.

  • name (str) – Name of workflow (default: hemodynamic_wf)

Parameters:

  • bold_t1 – BOLD image in T1w space, after the prescribed corrections (STC, HMC and SDC) when available.

  • boldmask – Bold fov mask

  • roi – Roi mask in T1w space

  • t1w – T1w image

  • t1w_mask_lesion – Mask of the lesion in T1w space

  • t1w_mask – Brain Mask of T1

  • t1w_tpms – List of tissue probability maps in T1w space

  • t1w_aseg – Segmentation of structural image, done with FreeSurfer.

  • confounds_file – TSV of all aggregated confounds.

Parameters:

maps – lagmap

Genrerate Registration plot with roi

fmristroke.workflows.bold.registration.init_lesionplot_wf(boldref, mem_gb: float, output_dir=None, name: str = 'lesion_plot_wf')[source]

Build a workflow to generate registration plots with lesions.

Parameters:

  • mem_gb (float) – Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV

  • name (str) – Name of workflow (default: lesion_plot_wf)

Parameters:

  • bold_ref_t1 – Bold reference

  • t1w – t1w image

  • t1w_roi – Roi mask in T1w space

  • t1w_mask – Mask of the skull-stripped template image

Parameters:

out_registration_plot – Path of the generated SVG file

Denoising

fmristroke.workflows.bold.denoise.init_denoise_wf(mem_gb: float, omp_nthreads: int, metadata: dict, pipelines: Pipelines, spaces: SpatialReferences, name: str = 'bold_denoise_wf')[source]

Build a workflow to denoise BOLD series.

This workflow denoises the BOLD series according to the specified denoising strategies.

Parameters:

  • mem_gb (float) – Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV

  • metadata (dict) – BIDS metadata for BOLD file

  • pipelines (Pipelines) – A container for storing denoising strategies.

  • spaces (py:class:~niworkflows.utils.spaces.SpatialReferences) – A container for storing, organizing, and parsing spatial normalizations. Composed of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs (e.g., MNI152Lin, MNI152NLin6Asym, MNIPediatricAsym), nonstandard references (e.g., T1w or anat, sbref, run, etc.), or a custom template located in the TemplateFlow root directory. Each Reference may also contain a spec, which is a dictionary with template specifications (e.g., a specification of {"resolution": 2} would lead to resampling on a 2mm resolution of the space).

  • name (str) – Name of workflow (default: bold_denoise_wf)

Parameters:

  • bold_t1 – BOLD image in T1 space, after the prescribed corrections (STC, HMC and SDC) when available.

  • boldmask – Bold fov mask in t1 space

  • anat2std_xfm – List of anatomical-to-standard space transforms generated during spatial normalization.

  • templates – List of templates that were applied as targets during spatial normalization.

  • confounds_file – TSV of all aggregated confounds.

  • confounds_metadata – JSON of confounds metadata file

Parameters:

  • bold_denoised_t1 – BOLD image in T1 denoised

  • bold_denoised_std – BOLD image in std spaces denoised

  • template – Template identifiers synchronized correspondingly to previously described outputs.

  • spatial reference – Spatial reference

  • pipeline – Pipeline identifyers

Combining runs

fmristroke.workflows.bold.concatenate.init_concat_wf(mem_gb: float, croprun: int, session_level: bool, name: str = 'concat_wf')[source]

Build a workflow to combine runs from the same session and task if multiple runs are available.

This workflow combines bold series, confounds and masks. It crops the beginning of the run if necesssary.

Parameters:

  • mem_gb (float) – Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV

  • croprun (:obj: int`) – crop beginning of bold run by n volumes.

  • session_level (bool) – wether to concatenate bold runs at session level

  • name (str) – Name of workflow (default: concat_wf)

Parameters:

  • bold_denoised_t1 – List of BOLD images in T1w space from the same session and task

  • bold_denoised_std – List of BOLD images in T1w space from the same session and task

  • boldmask_t1 – List of BOLD masks in T1w space from the same session and task

Parameters:

  • bold_denoised_t1 – Concatenated BOLD denoised image in T1w

  • bold_denoised_std – Concatenated BOLD denoised image in std space

  • boldmask_t1 – Bold mask for concatenated BOLD files

Connectivity

fmristroke.workflows.bold.connectivity.init_connectivity_wf(mem_gb: float, atlases: Atlases, pipelines: Pipelines, session_level: bool, conn_measure: list = ['correlation'], name: str = 'connectivity_wf')[source]

Build a workflow to generate connectivity matrices.

Parameters:

  • mem_gb (float) – Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV

  • conn_measure (:obj: str) – Measure to compute connectivity

  • atlases (:py:class: ~fmristroke.utils.atlas.Atlases) – A container for storing atlas for connectivity

  • pipelines (Pipelines) – A container for storing denoising strategies.

  • name (str) – Name of workflow (default: connectivity_wf)

Parameters:

  • bold_denoised – BOLD image denoised in standard space

  • boldmask – fov mask

  • mask_lesion_std – Mask of the lesion in std space

Parameters:

  • conn_mat – connectivity matrice

  • pipelines – Pipelines

  • atlases – Atlases

  • conn_measure – Conn_measure

  • pipelines – Pipelines

  • atlases – Atlases

  • conn_measure – Conn_measure