TimeseriesExtractor#

class neurocaps.extraction.TimeseriesExtractor(space='MNI152NLin2009cAsym', parcel_approach={'Schaefer': {'n_rois': 400, 'resolution_mm': 1, 'yeo_networks': 7}}, standardize=True, detrend=False, low_pass=None, high_pass=None, fwhm=None, use_confounds=True, confound_names='basic', fd_threshold=None, n_acompcor_separate=None, dummy_scans=None, dtype=None)[source]#

Timeseries Extractor Class.

Performs timeseries denoising, extraction, serialization (pickling), and visualization.

Parameters:

space (str, default=”MNI152NLin2009cAsym”) – The standard template space that the preprocessed bold data is registered to.
parcel_approach (ParcelConfig, ParcelApproach, or str, default={“Schaefer”: {“n_rois”: 400, “yeo_networks”: 7, “resolution_mm”: 1}}) – Specifies the parcellation approach to use. Options are “Schaefer”, “AAL”, or “Custom”. Can be initialized with parameters, as a nested dictionary, or loaded from a pickle file. For detailed documentation on the expected structure, see the type definitions for ParcelConfig and ParcelApproach in the “See Also” section.
standardize (bool or or None, default=True) –
Standardizes the timeseries (zero mean and unit variance using sample standard deviation). Always the final step in the pipeline.

Changed in version 0.25.0: No longer passed to Nilearn’s NiftiLabelsMasker and only performs standardization using sample standard deviation. Default behavior of standardizing using sample standard deviation is the same; however, when not None or False, standardizing is always done at the end of the pipeline to prevent any external standardization from needing to be done when censoring or extracting condition.

Note

Standard deviations below np.finfo(std.dtype).eps are replaced with 1 for numerical stability.
detrend (bool, default=False) –
Detrends the timeseries.

Changed in version 0.26.0: Default changed from True to False due to the redundancy of detrending when discrete cosine-basis regressors are used, which is included in the “basic” option for confound_names.
low_pass (float, int, or None, default=None) – Filters out signals above the specified cutoff frequency.
high_pass (float, int, or None`, default=None) – Filters out signals below the specified cutoff frequency.
fwhm (float, int, or None, default=None) – Applies spatial smoothing to data (in millimeters).
use_confounds (bool, default=True) –
If True, performs nuisance regression during timeseries extraction using the default or user-specified confounds in confound_names.

Important

Requires the confound tsv files to be in same directory as preprocessed BOLD images.
confound_names ({“basic”}, list[str], or None, default=”basic”) –
Names of confounds extracted from the confound tsv files if use_confounds=True.

If “basic”, the following confounds are used by default:
- All discrete cosine-basis regressors.
- Six head-motion parameters and their first-order derivatives.
- First six principal aCompCor components.
Important
- Confound names follow fMRIPrep’s naming scheme (versions >= 1.2.0).
- Wildcards are supported: e.g., “cosine*” matches all confounds starting with “cosine”.
fd_threshold (float, dict[str, float | int], or None, default=None) –
Threshold for volume censoring based on framewise displacement (FD). Computed only after dummy volumes are removed.
- If float, removes volumes where FD > threshold.
- If dict, the following subkeys are available (all non-required subkeys are None by default):
  - ”threshold”: A float (required). Removes volumes where FD > threshold.
  - ”outlier_percentage”: A float in interval [0,1]. Removes entire runs where proportion of censored volumes exceeds this threshold. Proportion calculated after dummy scan removal.
  Note
  
  A warning is issued when a run is flagged.
  
  If condition specified for task-based data in self.get_bold(), only considers volumes associated with the condition.
  - ”n_before”: An integer. Indicates the number of volumes to remove before each flagged volume.
  - ”n_after”: An integer. Indicates the number of volumes to remove after each flagged volume.
  - ”use_sample_mask”: A boolean. Controls when censoring is applied in the processing pipeline.
  Important
  
  When True:
  
  Passes a sample mask of censored volumes to Nilearn’s NiftiLabelsMasker.
  
  Sets clean__extrapolate=False to prevent interpolation of end volumes.
  
  Censoring is applied before nuisance regression.
  
  If condition is specified for task-based data in self.get_bold(), the timeseries is temporarily padded to extract the correct frames.
  
  When False or None:
  
  Full timeseries data is used during nuisance regression.
  
  Censoring is applied after nuisance regression.
  - ”interpolate”: A boolean. If True, uses scipy’s CubicSpline function` to perform cubic spline interpolation only on censored frames. Only performs interpolation if True.
  Note
  
  Interpolation is only performed on frames that are bounded by non-censored frames on both ends. For example, given a censor_mask=[0, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0] where “0” indicates censored high motion volumes and “1” indicates non-censored, low motion volumes, only the volumes at index 3, 5, 6, 7, and 9 would be interpolated.
Important
- A column named “framewise_displacement” must be available in the confounds file.
- use_confounds must be set to True.
- Do not specify “framewise_displacement” in confound_names.
- See Nilearn’s documentation for details on censored volume handling when “use_sample_mask” is True:
  Signal Clean
  
  NiftiLabelsMasker
- If “interpolate” is True, then interpolation is only applied after the nuisance regression and parcellation steps have been completed.
- See Scipy’s CubicSpline documentation.
n_acompcor_separate (int or None, default=None) –
Number of aCompCor components to extract separately from the white-matter (WM) and CSF masks. Uses first “n” components from each mask separately. For instance, if n_acompcor_separate=5, then the the first 5 WM components and the first 5 CSF components (totaling 10 components) are regressed out.
Important
- use_confounds must be set to True.
- If specified, this parameter overrides any aCompCor components listed in confound_names.
dummy_scans (int, dict[str, bool | int], “auto”, or None, default=None) –
Number of initial volumes to remove before timeseries extraction.
- If int, removes first “n” volumes.
- If auto, removes first “n” volumes based on “non_steady_state_outlier_XX” columns.
- If dict, the following keys are supported (all non-required subkeys are None by default):
  - ”auto”: A boolean (required). Removes first “n” volumes based on “non_steady_state_outlier_XX” columns.
  - ”min”: An integer. Minimum volumes to remove when auto is set to True. If “auto” finds 2 outliers but {"min": 3}, removes 3 volumes.
  - ”max”: An integer. Maximum volumes to remove when auto is set to True. If “auto” finds 6 outliers but {"max": 5}, removes 5 volumes.
Important
- ”auto” and dictionary option requires use_confounds to be True and “non_steady_state_outlier_XX” to be present in the confounds tsv file.
- ”min” and “max” keys only apply when “auto” is True.
dtype (str or “auto”, default=None) – The NumPy dtype to convert NIfTI images to.

Properties#

space: str

The standard template space that the preprocessed BOLD data is registered to. This property is also settable.

parcel_approach: ParcelApproach

Parcellation information with “maps” (path to parcellation file), “nodes” (labels), and “regions” (anatomical regions or networks). Returns a deep copy.

signal_clean_info: dict[str, bool | int | float | str] or None

Dictionary containing signal cleaning parameters. Returns a deep copy.

task_info: dict[str, str | int] or None

Dictionary containing all task-related information such. Defined after running self.get_bold().

subject_ids: list[str] or None

A list containing all subject IDs that have retrieved from PyBIDS and subjected to timeseries extraction. Defined after running self.get_bold().

n_cores: int or None

Number of cores used for multiprocessing with Joblib. Defined after running self.get_bold().

subject_timeseries: SubjectTimeseries or None

A dictionary mapping subject IDs to their run IDs and their associated timeseries (TRs x ROIs) as a NumPy array. Can be deleted using del self.subject_timeseries. Defined after running self.get_bold(). This property is also settable (accepts a dictionary or pickle file).

qc: dict or None

A dictionary reporting quality control, which maps subject IDs to their run IDs and information related to the number of frames scrubbed and interpolated as well as the mean and standard deviation of continuous high motion segments. Statistics for each subject’s run are only reported when fd_threshold is specified, a valid confound tsv file containing the “framewise_displacement” column is found, and the run is not skipped.

{"subjectID": {"run-ID": {"mean_fd": float, "std_fd": float, ...}}}

`__str__`	Print Current Object State.
`get_bold`	Retrieve Preprocessed BOLD Data from BIDS Datasets.
`report_qc`	Report Quality Control Information.
`timeseries_to_pickle`	Save the Extracted Subject Timeseries.
`visualize_bold`	Plot the Extracted Subject Timeseries.