`neurocaps.extraction`.TimeseriesExtractor#

class TimeseriesExtractor(space='MNI152NLin2009cAsym', parcel_approach={'Schaefer': {'n_rois': 400, 'resolution_mm': 1, 'yeo_networks': 7}}, standardize='zscore_sample', detrend=True, 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 ({"zscore_sample", "zscore", "psc", True, False}, default="zscore_sample") – Standardizes the timeseries.
detrend (bool, default=True) – Detrends the timeseries.
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 cosine-basis parameters.
- Six head-motion parameters and their first-order derivatives.
- First six combined 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”.
Changed in version 0.23.0: Changed default from None to "basic". The "basic" option provides the same functionality that None did in previous versions.
fd_threshold (float, dict[str, float | int], or None, default=None) –
Threshold for volume censoring based on framewise displacement (FD).
- If float, removes volumes where FD > threshold.
- If dict, the following subkeys are available:
  - ”threshold”: A float (Default=None). Removes volumes where FD > threshold.
  - ”outlier_percentage”: A float in interval [0,1] (Default=None). 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 (Default=None). Indicates the number of volumes to remove before each flagged volume.
  - ”n_after”: An integer (Default=None). Indicates the number of volumes to remove after each flagged volume.
  - ”use_sample_mask”: A boolean (Default=None). 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 (Default=None). If True, uses scipy’s CubicSpline function with extrapolate=False to perform cubic spline interpolation on censored frames.
  Note
  
  Interpolation is only performed on frames that are flanked by non-censored frames on both ends. For example, given a censor_mask=[0, 0, 1, 0, 1, 0, 0, 1, 0, 1, 0, 0] where “0” indicates censored volumes, only the volumes at index 3, 5, 6, and 8 would be interpolated. If False or
  
  Added in version 0.22.3: “interpolate” key added.
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
- When “use_sample_mask” is False and standardize is not False, applying an additional within-run standardization (using neurocaps.analysis.standardize) is recommended after outlier removal.
- If “interpolate” is True, then interpolation is only applied 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], or None, default=None) –
Number of initial volumes to remove before timeseries extraction.
- If int, removes first “n” volumes.
- If dict, the following keys are supported:
  - ”auto”: A boolean (Default=None). If True, automatically determines dummy scans from fMRIPrep confounds using the number of “non_steady_state_outlier_XX” columns in the confounds tsv file.
  - ”min”: An integer (Default=None). Minimum volumes to remove when auto is set to True. If “auto” finds 2 outliers but {"min": 3}, removes 3 volumes.
  - ”max”: An integer (Default=None). Maximum volumes to remove when auto=True. If “auto” finds 6 outliers but {"max": 5}, removes 5 volumes.
Important

”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.
parcel_approach: ParcelApproach: Parcellation information with “maps” (path to parcellation file), “nodes” (labels), and “regions” (anatomical regions or networks).
signal_clean_info: dict[str, bool | int | float | str] or None: Dictionary containing signal cleaning parameters.
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().

`get_bold`(bids_dir, task[, session, runs, ...])	Retrieve Preprocessed BOLD Data from BIDS Datasets.
`timeseries_to_pickle`(output_dir[, filename])	Save the Extracted Subject Timeseries.
`visualize_bold`(subj_id[, run, roi_indx, ...])	Plot the Extracted Subject Timeseries.

neurocaps.extraction.TimeseriesExtractor#

Properties#

`neurocaps.extraction`.TimeseriesExtractor#