fmridenoise.interfaces package

Submodules

fmridenoise.interfaces.bids module

class fmridenoise.interfaces.bids.BIDSDataSink(from_file=None, resource_monitor=None, ignore_exception=False, **inputs)

Bases: nipype.interfaces.io.IOBase

Copies files created by workflow to bids-like folder.

_always_run = True

_list_outputs()

List the expected outputs

input_spec

alias of fmridenoise.interfaces.bids.BIDSDataSinkInputSpec

output_dir_pattern = '{bids_dir}/derivatives/{derivative}/[ses-{session}/][sub-{subject}/]'

output_path_pattern = '{bids_dir}/derivatives/{derivative}/[ses-{session}/][sub-{subject}/][sub-{subject}_][ses-{session}_][task-{task}_][run-{run}_][pipeline-{pipeline}_][desc-{desc}_]{suffix}.{extension}'

output_spec

alias of fmridenoise.interfaces.bids.BIDSDataSinkOutputSpec

class fmridenoise.interfaces.bids.BIDSDataSinkInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.bids.BIDSDataSinkOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

class fmridenoise.interfaces.bids.BIDSGrab(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

For each list of paths selects one file for given set of parameters - subject, session, task.

_run_interface(runtime)

Core function that executes interface

_select_one(_list: List[str]) → str

Wrapper for select_one that uses class instance variable. :param _list: list of file paths :type _list: List[str]

Returns

resulting file path meeting criteria

Return type

str

input_spec

alias of fmridenoise.interfaces.bids.BIDSGrabInputSpec

output_spec

alias of fmridenoise.interfaces.bids.BIDSGrabOutputSpec

static select_one(_list: List[str], subject: str, task: str, session: str, run: str) → str

For given list of file paths returns one path for given subject, session and task. If no paths meet criteria empty string is returned instead. If more than one path is found ValueError is raised. :param _list: list of file paths :type _list: List[str] :param subject: subject identifier without ‘sub-‘ :type subject: str :param session: session identifier without ‘ses-‘ :type session: str :param task: task identifier without ‘task-‘ :type task: str :param run: run identifier without ‘run-‘ :type run: str

Returns

resulting file path meeting criteria

Return type

str

class fmridenoise.interfaces.bids.BIDSGrabInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.bids.BIDSGrabOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

class fmridenoise.interfaces.bids.BIDSValidate(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

Interface responsible for calling BIDSLayout and validating file structure.

It should output to:

• layout (-> BIDSGrab)

• task, session, subject (-> iterNodes)

• pipeline (-> ?)

• tr_dict (-> Denoiser)

It should raise exception when:

• user specified incorrect flags (there are no matching files)

• some files are missing e.g. these for AROMA pipeline, when it is required

_run_interface(runtime)

Core function that executes interface

static get_entity_files(layout: bids.layout.layout.BIDSLayout, include_no_aroma: bool, include_aroma: bool, entity: dict) → tuple

Checks if all required files are present for single entity defined by subject, session and task labels. If include_aroma is True also checks for AROMA file. Note that session argument can be undefined.

Args:

Returns

Union[bool, dict], dict)

Return type

(missing

input_spec

alias of fmridenoise.interfaces.bids.BIDSValidateInputSpec

output_spec

alias of fmridenoise.interfaces.bids.BIDSValidateOutputSpec

static validate_derivatives(bids_dir: str, derivatives: Union[str, List[str]]) → Tuple[List[str], List[str]]

Validate derivatives argument provided by the user before calling layout. It creates required full path for derivatives directory. Also returns scope required for queries.

Parameters

• bids_dir (str) – Path to bids root directory.

• derivatives (Union[str, List[str]]) – str or list(str) Derivatives to use for denoising.

Returns

Validated derivatives list. scope (list):

Right scope keyword used in pybids query.

Return type

derivatives_valid (list)

static validate_files(layout: bids.layout.layout.BIDSLayout, tasks: List[str], sessions: List[str], subjects: List[str], runs: List[str], include_aroma: bool, include_no_aroma: bool)

Checks if for all parameters permutations every file (confounds.tsv, confounds.json, img, img with aroma) exists. Aroma and no aroma files are checked if proper flag is set to true.

Parameters

• layout (BIDSLayout) – BIDSLayout

• tasks (List[str]) – tasks that are expected to exist

• sessions (List[str]) – tasks that are expected to exist

• subjects (List[str]) – subjects that are expected to exist

• runs (List[str]) – runs that are expected to exists

• include_aroma (bool) – check for aroma files for every task/session/subject configuration

• include_no_aroma (bool) – check for no aroma files for every task/session/subject configuration

Returns

entity files and tuple with all tasks, subjects, sessions

class fmridenoise.interfaces.bids.BIDSValidateInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.bids.BIDSValidateOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

exception fmridenoise.interfaces.bids.MissingFile

Bases: OSError

fmridenoise.interfaces.bids._fill_empty_lists(layout: bids.layout.layout.BIDSLayout, subjects: list, tasks: list, sessions: list, runs: List[str])

If filters are not provided by the user, load them from layout.

fmridenoise.interfaces.bids._lists_to_entities(subjects: list, tasks: list, sessions: List[str], runs: List[str])

Convert lists of subjects, tasks and sessions into list of dictionaries (entities). It handles empty session list.

fmridenoise.interfaces.confounds module

class fmridenoise.interfaces.confounds.Confounds(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

Preprocess and filter confounds table according to denoising pipeline.

This interface reads raw confounds table (fmriprep output) and process it retaining regressors of interest and creating additional regressors if needed. Additionally, it creates summary file containing all relevant information about confounds. This interface operates on single BIDS entity i.e. single subject, task and (optionally) session.

Output filenames for both processed confounds and summary JSON have identical base but different extensions, since they are describing the same piece of data. They are created by replacing regressors suffix from original filenames with expression pipeline-<pipeline_name>.

Summary contains fields:

‘mean_fd’:

Mean framewise displacement.

‘max_fd’:

Highest recorded framewise displacement.

‘n_conf’:

Total number of confounds included.

‘include’:

Decision about subject inclusion in connectivity analysis based on three criteria: (1) mean framewise displacement is lower than specified by the pipeline, (2) max framewise displacement did not exceed 5mm and (3) percentage of outlier scans did not exceed 20%. Note that if spikes strategy is not specified, include flag defaults to True.

‘n_spikes’:

Number of outlier scans (only if spikes strategy is specified).

‘perc_spikes’:

Percentage of outlier scans (only if spikes strategy is specified).

_create_spike_regressors()

_create_summary_dict(subject: str, session: str, task: str, run: str)

_filter_acompcors()

_filter_motion_parameters()

_filter_tissue_signals()

_inclusion_check()

Decide if subject should be included in connectivity analysis

_retain(regressor_names: List[str])

Copies selected regressors from conf_raw to conf_prep.

_run_interface(runtime)

Core function that executes interface

conf_prep_pattern = 'sub-{subject}[_ses-{session}]_task-{task}[_run-{run}]_pipeline-{pipeline}_desc-{desc}.tsv'

conf_summary_pattern = 'sub-{subject}[_ses-{session}]_task-{task}[_run-{run}]_pipeline-{pipeline}_desc-{desc}_summary.json'

input_spec

alias of fmridenoise.interfaces.confounds.ConfoundsInputSpec

output_spec

alias of fmridenoise.interfaces.confounds.ConfoundsOutputSpec

class fmridenoise.interfaces.confounds.ConfoundsInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.confounds.ConfoundsOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

class fmridenoise.interfaces.confounds.GroupConfounds(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

_run_interface(runtime)

Core function that executes interface

file_pattern = '[ses-{session}_]task-{task}_[run-{run}]_pipeline-{pipeline}_groupConfSummary.tsv'

input_spec

alias of fmridenoise.interfaces.confounds.GroupConfoundsInputSpec

output_spec

alias of fmridenoise.interfaces.confounds.GroupConfoundsOutputSpec

class fmridenoise.interfaces.confounds.GroupConfoundsInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.confounds.GroupConfoundsOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

fmridenoise.interfaces.connectivity module

class fmridenoise.interfaces.connectivity.Connectivity(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

_run_interface(runtime)

Core function that executes interface

carpet_plot_pattern = 'sub-{subject}[_ses-{session}]_task-{task}[_run-{run}]_pipeline-{pipeline}_carpetPlot.png'

conn_file_pattern = 'sub-{subject}[_ses-{session}]_task-{task}[_run-{run}]_pipeline-{pipeline}_connMat.npy'

input_spec

alias of fmridenoise.interfaces.connectivity.ConnectivityInputSpec

matrix_plot_pattern = 'sub-{subject}[_ses-{session}]_task-{task}[_run-{run}]_pipeline-{pipeline}_matrixPlot.png'

output_spec

alias of fmridenoise.interfaces.connectivity.ConnectivityOutputSpec

class fmridenoise.interfaces.connectivity.ConnectivityInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.connectivity.ConnectivityOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

class fmridenoise.interfaces.connectivity.GroupConnectivity(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

_run_interface(runtime)

Core function that executes interface

group_corr_pattern = '[ses-{session}_]task-{task}_[run-{run}_]pipeline-{pipeline}_groupCorrMat.npy'

input_spec

alias of fmridenoise.interfaces.connectivity.GroupConnectivityInputSpec

output_spec

alias of fmridenoise.interfaces.connectivity.GroupConnectivityOutputSpec

class fmridenoise.interfaces.connectivity.GroupConnectivityInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.connectivity.GroupConnectivityOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

fmridenoise.interfaces.denoising module

class fmridenoise.interfaces.denoising.Denoise(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

Denoise functional images using filtered confounds.

This interface uses filtered confounds table and temporal (bandpass) filtering to denoise functional images. It wraps around nilearn clean_img function to create and save denoised file.

At least one of two inputs should be passed to this interface depending on denoising strategy. If denoising assumes aroma, fmri_prep_aroma file should be provided, otherwise fmri_prep file should be provided.

Temporal filtering can be requested by specifying either one or two optonal inputs: low_pass and high_pass. These reflect cut-off values (in Hertz) for low-pass and high-pass temporal filters. Note that if either low_pass or high_pass argument is provided, tr_dict containing task name as key and task TR (in seconds) as value should also be provided (because in that case clean_img requires TR).

Output filename reflecting denoised filename is created by adding suffix

‘pipeline-<pipeline_name>_desc-denoised_bold’

to existing filename (desc-preproc is replaced with desc-denoised).

_load_confouds()

Load confounds from tsv file. If confounds is empty file (in case of null pipeline) confounds keyword argument for clean_img should be None.

Creates:

_confounds (attribute):

Either None (for null pipeline) or np.ndarray of confounds if conf_prep is not empty.

_run_interface(runtime)

Core function that executes interface

_validate_filtering(task)

Validate input arguments related to temporal filtering.

Creates:

_filtering_kwargs (attribute):

Dictionary of optional keyword arguments passed to clean_img. Empty if no temporal filtering is requested.

_validate_fmri_prep_files()

Check if correct file is provided according to aroma option in pipeline dictionary.

Creates:

_fmri_file (attibute):

preprocessed fmri file (either with or without aroma)

fmri_denoised_pattern = 'sub-{subject}[_ses-{session}]_task-{task}[_run-{run}]_space-{space}_pipeline-{pipeline}_desc-denoised_bold.nii.gz'

input_spec

alias of fmridenoise.interfaces.denoising.DenoiseInputSpec

output_spec

alias of fmridenoise.interfaces.denoising.DenoiseOutputSpec

class fmridenoise.interfaces.denoising.DenoiseInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.denoising.DenoiseOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

fmridenoise.interfaces.pipeline_selector module

class fmridenoise.interfaces.pipeline_selector.PipelineSelector(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

_run_interface(runtime)

Core function that executes interface

input_spec

alias of fmridenoise.interfaces.pipeline_selector.PipelineSelectorInputSpecification

output_spec

alias of fmridenoise.interfaces.pipeline_selector.PipelineSelectorOutPutSpecification

class fmridenoise.interfaces.pipeline_selector.PipelineSelectorInputSpecification(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.pipeline_selector.PipelineSelectorOutPutSpecification(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

fmridenoise.interfaces.quality_measures module

class fmridenoise.interfaces.quality_measures.PipelinesQualityMeasures(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

_make_summary_figures(entities_dict: dict) → None

Makes summary figures for all quality measures

_run_interface(runtime)

Core function that executes interface

data_files_pattern = '[ses-{session}_]task-{task}[_run-{run}][_desc-{desc}]_{suffix}.{extension}'

static edges_weight_to_dataframe(edges_weight: List[Dict[str, numpy.ndarray]], edges_weight_clean: List[Union[traits.trait_base._Undefined, Dict[str, numpy.ndarray]]]) → Tuple[pandas.core.frame.DataFrame, pandas.core.frame.DataFrame]

Converts input (input spec) edges_weight and edges_weight_clean from previous steps of data processing to dataframe :param edges_weight: list of dictionaries with pipeline name and array of floats :param edges_weight_clean: list of dictionaries with pipeline name and array of floats

Returns

dataframe with flatten input data

static fc_fd_corr_values_to_dataframe(fc_fd_corr_values: List[Dict[str, numpy.ndarray]], fc_fd_corr_values_clean: List[Union[traits.trait_base._Undefined, Dict[str, numpy.ndarray]]]) → Tuple[pandas.core.frame.DataFrame, pandas.core.frame.DataFrame]

Converts input (input spec) fc_fd_corr_values and fc_fd_corr_values_clean from previous steps of data processing to dataframe :param fc_fd_corr_values: list of dictionaries with pipeline name and array of floats :param fc_fd_corr_values_clean: list of dictionaries with pipeline name and array of floats

Returns

dataframe with flatten input data

input_spec

alias of fmridenoise.interfaces.quality_measures.PipelinesQualityMeasuresInputSpec

output_spec

alias of fmridenoise.interfaces.quality_measures.PipelinesQualityMeasuresOutputSpec

static pipeline_summaries_to_dataframe(pipelines_fd_fd_summary_raw: List[List[Dict]]) → pandas.core.frame.DataFrame

Converts standard fc_fd_summary from previous steps of data processing to dataframe :param pipelines_fd_fd_summary_raw: list of 2 elements list (high motion and no high motion) :param with dictionaries containing information from quality measures interface output: :param Check tests.manual.plotting_examples for reference data.:

Returns

dataframe with flatten input data

plot_pattern = '[ses-{session}_]task-{task}_[run-{run}_]desc-{desc}_plot.svg'

class fmridenoise.interfaces.quality_measures.PipelinesQualityMeasuresInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.quality_measures.PipelinesQualityMeasuresOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

class fmridenoise.interfaces.quality_measures.QualityMeasures(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

_calculate_quality_measures(group_conf_summary: pandas.core.frame.DataFrame, group_corr_mat: numpy.ndarray, distance_matrix: numpy.ndarray) → Tuple[List[dict], numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, Set[str]]

static _distance_dependence(fc_fd_corr: numpy.ndarray, distance_vector: numpy.ndarray) → float

Calculates percent of significant FC-FD correlations (uncorrected).

property _enough_clean_subjects

classmethod _perc_fc_fd_uncorr(fc_fd_pval: numpy.ndarray) → float

Calculates percent of significant FC-FD correlations (uncorrected).

classmethod _quality_measure(group_conf_summary: pandas.core.frame.DataFrame, distance_vec: numpy.ndarray, group_corr_vec: numpy.ndarray, all_subjects: bool) → Tuple[dict, numpy.ndarray, numpy.ndarray, List[str]]

Calculates :param group_conf_summary: Conf summary for all subjects :param distance_vec: Distance matrix flatten into vector :param group_corr_vec: :param all_subjects: True if all subjects should be included, False if only ‘low motion’ subjects

Returns

dictionary with summary of various numerical parameters of processed data vector of mean correlations between edges vector of correlations between edges weights and mean framewise displacement list of excluded subjects

Return type

Tuple with

_run_interface(runtime)

Core function that executes interface

_validate_group_conf_summary(group_conf_summary: pandas.core.frame.DataFrame)

Checks if correct summary data are provided. Raises exceptions when data is not valid. Each row should contain data for one subject.

property _warnings

static calculate_fc_fd_correlations(group_conf_summary: pandas.core.frame.DataFrame, group_corr_vec: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray]

Calculates correlations between edges weights and mean framewise displacement.

input_spec

alias of fmridenoise.interfaces.quality_measures.QualityMeasuresInputSpec

output_spec

alias of fmridenoise.interfaces.quality_measures.QualityMeasuresOutputSpec

plot_pattern = '[ses-{session}_]task-{task}_[run-{run}_]pipeline-{pipeline}_desc-{desc}.svg'

pval_tresh = 0.05

class fmridenoise.interfaces.quality_measures.QualityMeasuresInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.quality_measures.QualityMeasuresOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

fmridenoise.interfaces.report_creator module

class fmridenoise.interfaces.report_creator.ReportCreator(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

_always_run = True

_run_interface(runtime)

Core function that executes interface

input_spec

alias of fmridenoise.interfaces.report_creator.ReportCreatorInputSpec

class fmridenoise.interfaces.report_creator.ReportCreatorInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

fmridenoise.interfaces.smoothing module

class fmridenoise.interfaces.smoothing.Smooth(from_file=None, resource_monitor=None, **inputs)

Bases: nipype.interfaces.base.core.SimpleInterface

_run_interface(runtime)

Core function that executes interface

input_spec

alias of fmridenoise.interfaces.smoothing.SmoothInputSpec

output_spec

alias of fmridenoise.interfaces.smoothing.SmoothOutputSpec

smooth_file_pattern = 'sub-{subject}[_ses-{session}]_task-{task}[_run-{run}]_space-{space}_desc-Smoothed_bold.nii.gz'

class fmridenoise.interfaces.smoothing.SmoothInputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.BaseInterfaceInputSpec

class fmridenoise.interfaces.smoothing.SmoothOutputSpec(**kwargs)

Bases: nipype.interfaces.base.specs.TraitedSpec

fmridenoise.interfaces.utility module

class fmridenoise.interfaces.utility.FlattenIdentityInterface(fields, mandatory_inputs=True, flatten_fields=(), **inputs)

Bases: nipype.interfaces.utility.base.IdentityInterface

Identity interface that can also flatten some of it’s fields before passing them forward

_list_outputs()

List the expected outputs

Module contents